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VOLUME 4 


PROGRAM DEVELOPMENT TOOLS 


This volume contains programming aids for the PS 300 programmer. The programs 
documented in this volume are distributed on the PS 300 A1 Firmware tape. Each 
programming aid is independent of the others and has its own level of limited support. 
Consult the limited support disclaimer on the front page of each document in this 
volume. 

This volume contains the following sections. 


PS 300 APPLICATION NOTES 

The PS 300 Application Notes is a collection of programming samples and 
graphical applications for PS 300 users. Evans & Sutherland's own programming 
staff and PS 300 users outside the company have contributed and continue to 
contribute to the Notes. 


FUNCTION NETWORK EDITOR 

The Function Network Editor is a graphical program named NETEDIT which lets 
you create a function network as a diagram on the PS 300 display. Editing menus 
are used to build a network of hierarchically structured "black boxes" which may 
contain more detailed representations of parts of the network. When the 
diagram is complete, an ASCII code file can be generated which contains the 
PS 300 commands needed to build the network. 

The program is written in Pascal \I2.2 and runs under VAX/VMS 3.3 and higher. 


FUNCTION NETWORK DEBUGGER 

The Function Network Debugger program, NETPRQBE, was developed at Evans 
& Sutherland as an aid to debugging function networks. The program displays the 
activity of a network as it manipulates data. Each function output used in the 
network is displayed on a separate display line in a 15-item page. Each page 
shows the name of the function and number of the output, the value last output, 
and optionally, a count of how many times the output has fired. Function keys 
provide control over which of twenty pages are displayed, clear the currently 
displayed values, and disable the display. 

NETPRQBE is written in Pascal \I2.2 and runs under VAX/VMX 3.3 and higher. 




CHARACTER FONT EDITOR 


MAKEFONT is a graphical character font editing program that allows you to edit 
an existing character font or create a new one. It is an interactive, menu-driven 
program that displays characters in a 128- or 256-character font. Each 
character can be edited to create a new shape. Different fonts can be combined 
into a new font, and original fonts can be created from scratch. 

MAKEFONT is written in Pascal Ml.l and runs under VAX/VMS 3.3 and higher. 


PS 300 ADVANCED PROGRAMMING 

PS 300 Advanced Programming is a detailed reference provided for experienced 
programmers both as a guide to writing their own functions for the PS 300 and 
also for doing direct physical I/O across the high-speed parallel interface. Some 
sections might also be of interest for anyone wanting more information about 
how the PS 300 creates and manipulates data structures. 

The programmer using the user-written function and advanced user-written 
function facilities should be familiar with the Pascal programming language, the 
types of functions provided by E&S, the acceptable inputs to functions, and the 
use of functions in the PS 300 system. 

PS 300 Advanced Programming manual is distributed to you as part of your 
A2.\/02 Release Notes package. 

UPDATES FUNCTION 

The Updates Function (F:USERUPD) provides a method of rapidly updating 
viewing transformations and characters. It is intended for use in applications 
such as robotics and animation. 

The Updates Function was created to allow data structures to be updated quickly 
by transferring data from the host to the PS 300 very rapidly. F:USERUPD is an 
enhancement included with Graphics Firmware Version A1 that can be used with 
all PS 300 interfaces and all members of the PS 300 family of computers except 
the PS 340. 






APPLICATION NOTES 



The PS 300 APPLICATION NOTES is a collection of useful information and applications 
for PS 300 users. Contributions to the NOTES come from inside and outside of 
Evans & Sutherland. Each note includes the author’s name and company. 

In the course of working with the PS 300, many of you will discover or develop ways of 
using it that may be valuable for a wide range of applications. By publishing PS 300 
APPLICATION NOTES, E&S is acting as a clearinghouse to make your ideas and 
techniques generally available to other users. 

These notes might describe an intricate function network that performs an important 
operation or show a new and useful way of structuring data. Or they may provide 
something as simple as "programming" conventions or debugging methods that have 
helped you. In other words, almost any idea that you think may be useful for other 
PS 300 users is a candidate for the PS 300 APPLICATION NOTES. 

Please submit an Application Note for each idea you have to Ec?cS. We will compile 
them and distribute them periodically to all PS 300 sites (we may, of course, not be able 
to publish every note submitted to us). Following is a sample form with instructions for 
filling it out and a second, blank form. Although it is not necessary to use the blank 
form provided here when you submit an Application Note, please follow the same 
format. (You may want to photocopy the blank form and use it for submissions.) 

The notes themselves are numbered arbitrarily for referencing only. Each is also 
referenced in the Index according to category (a list of each note's categories appears 
at the beginning of that note). 



You should be aware that the NOTES is not a supported product of E&S — they have 
been written by PS 300 users and have not been rigorously tested. If you encounter 
errors or bugs in these applications when you use them, please notify us at E&S. Submit 
your Application Notes and send any comments you may have to: 

Neil Harrington 
Evans & Sutherland 
P.O. Box 8700 

Salt Lake City, Utah 8A108 


FORMAT NOTE 

When actual code appears in an Application Note, the PS 300 commands are written 
with essential syntax in caps. Non-essential syntax is in lower case. "BEGIN_Structure", 
for instance, indicates that it is necessary to enter only "BEGIN S". 
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PS 300 APPLICATION NOTES Form Instructions 


(Title of Note Here) 


Your Name 

Department 

Company 

City 

Date 


CATEGORIES: 

List all possible categories for this note, for example: data structuring, function 
networks, command usage, host communications, animation, transformations, and so 
on. These categories are just examples, of course — your note will possibly fall into 
different ones. 


DESCRIPTION 

Briefly describe the function or application. Then tell WHY the new application is 
useful — what need it fills, what new thing it does, or what old thing it does in a new 
and easier way. 


IMPLEMENTATION 

Insert specific details about using the application. If the procedure is complex, describe 
it *'top-down": 

FIRST explain the ”big picture” or supply a block diagram 

THEN describe in detail each piece of the overall description or block in the 
diagram. 

Don’t start at the level of greatest detail right off — with the code itself, for example 
— unless the application is extremely simple. 


NOTES, EXAMPLES 

Include an example of the application. For users, this could mean the difference 
between understanding and not understanding how to use your application when they 
can’t find their way through the DESCRIPTION and IMPLEMENTATION. 

Also put here any warnings or side notes you think might help someone to understand 
and use your application. 



PS 300 APPLICATION NOTES Form 



Title: 


Your Name 

Department 

Company 

City 

Date 


CATEGORIES: 


DESCRIPTION 


o 

IMPLEMENTATION 


NOTES, EXAMPLES 
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PS 300 APPLICATION NOTE #1 


Cursor Redefinition 


Kerry Evans 
Systems Engineering 
Evans & Sutherland 
Salt Lake City, Utah 
December 1981 


CATEGORIES: Screen cursor, data structuring 
DESCRIPTION 

This describes hov\/ the screen cursor may be redefined to be a symbol other than the 
default cursor, v\/hich is an "X". 


IMPLEMENTATION 



The default cursor is defined as a vectorjist by a command of the form: 


CURSOR := VECtor list ITEMized n = A 
P -.03*5, -.035 
L .035, .035 

P -.035, .035 
L .035, -.035; 


To redefine the cursor as a square, simply redefine "CURSOR" in the following manner: 


CURSOR := VECtor list ITEMized n = 5 


-.035, 

-.035 

-.035, 

.035 

.035, 

.035 

.035, 

-.035 

-.035, 

-.035; 


NOTES, EXAMPLES 

The original cursor definition is lost until redefined in its original form by the user or 
until the PS 300 is powered on again. The INITialize command does NOT restore the 
default cursor definition. 
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PS 300 APPLICATION NOTE #2 


o 

Defining a Dynamic Cursor 


Kerry Evans 
Systems Engineering 
Evans &. Sutherland 
Salt Lake City, Utah 
December 1981 


CATEGORIES: Screen cursor, data structuring 
DESCRIPTION 

The screen cursor may be redefined to provide tv\/o different shapes — one when the 
data tablet pen tipswitch is up or open, and another when it is down 
or closed. 



IMPLEMENTATION 

Redefine the cursor as 

CURSOR := BEGIN Structure 
UP DOWN := SET conditional BIT 1 OFF; 

IF conditional B’lT 1 is ON THEN C_SQUARE; 

IF conditional_BIT 1 is OFF THEN C_CROSS; 
ENDStructure; 


C SQUARE := VECtor list ITEMized n = 5 
-.035,' -.035 
-.035, .035 

.035, .035 

.035, -.035 

-.035, -.035; 


C CROSS := VECtor list ITEMized n = 4 
P -.0'35, -.035 
L .035, .035 

P .035, -.035 
L -.035, .035; 


O 
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PS 300 APPLICATION NOTE #2 


Defining a Dynamic Cursor 



Now connect the data tablet tipswitch Boolean value (output 2) to control which cursor 
symbol is displayed: 

CONNect Tabletin<2>:<l>CURSOR.UP_DOWN; 


NOTES, EXAMPLES 

The original cursor definition is lost until redefined in its original form by the user or 
until the PS 300 is powered on again. The INITialize command does NOT restore the 
default cursor definition. 
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PS 300 APPLICATION NOTE #3 


World-Space Rotations 


Neil Harrington 
Marketing Software Support 
Evans & Sutherland 
Salt Lake City, Utah 
February 1982 


CATEGORIES: World-space rotations, object-space rotations, screen-space 
rotations 


DESCRIPTION 

A very desirable way of performing three-dimensional rotations is to know beforehand 
just what direction the object you are rotating is going to move. One way of doing this 
is to perform world-space (world-centered) rotations — that is, when you turn, say, the 
X rotation dial, you know the rotation will be about the world-space X axis. Likewise, 
of course, for Y and Z rotations. (See also object-space rotations.) 
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PS 300 APPLICATION NOTE #3 


World-Space Rotations 





Figure 3-1. World-Space Rotations 


IMPLEMENTATION 

To get true world-space rotations, the rotations need to be processed in the order that 
they come in (that is, they need to be post-concatenated to the current matrix). The 
network to do this is shown in the diagram below. 
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PS 300 APPLICATION NOTE #3 



World-Space Rotations 


DIALS<i) 

T80 


DIALS<j) 

180 
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—I F:X] 
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F; XROTATE —. 


WSL^ymu / c 


FrMULC 


WSi^yro fafe 


F:YROTATE 


WS^ro fa fe 


n 


FrCMUL 


( / )on data node) 


DIALS<k) 

180 


WS^mu/c 


I FrMULC 
_c| 


WS^ro ta fa j 

FrZROTATE [ —* 


(Initialize ( f }fFS^ro tat e to the identity 
matrix by sending 0 to {1)WS^esei) 


IAS0228 


Figure 3-2. World-Space Rotation Networks 

ri 


The output of the last function should also be connected to the appropriate rotation 
node in the data structure. 


NOTES, EXAMPLES 

If you are rotating an object about the world-space axes and viewing it from the 
negative Z axis, the space screen coordinates and world-space coordinates will coincide 
— the space-screen rotations will in effect be the same as the world-space rotations. 

There should only be one rotation node in the data structure (not one each for X, Y, and 
Z rotations). This node can be created with the ROTate X, ROTate Y, or ROTate Z 
commands. 

To reset the network and rotation node in the data structure, just put an identity matrix 
on input <1> of W5_Rotation. This can be done by connecting an instance of 
F:XROTATE to it and sending a 0 to input <1> of WS_Reset. 












PS 300 APPLICATION NOTE #4 
Object-Space Rotations 


Neil Harrington 
Marketing Software Support 
Evans & Sutherland 
Salt Lake City, Utah 
February 1982 


CATEGORIES: Object-space rotations, world-space rotations, data-space rotations 

DESCRIPTION 

A very desirable way of performing three-dimensional rotations is to know beforehand 
just what direction the object you are rotating is going to move. One way of doing this 
is to perform object-space (object-centered) rotations — that is, when you turn, say, 
the X rotation dial, you know the rotation will be about the X axis of the original object 
definition space. Likewise, of course, for Y and Z rotations. (See also world-space 
rotations). 
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PS 300 APPLICATION NOTE #4 


Object-Space Rotations 







IAS0229 


Figure 4-1. Object-Space Rotations 


IMPLEMENTATION 

To get true object space rotations, the rotations need to be processed in the reverse 
order that they come in (that is, they need to be pre-concatenated to the current 
matrix). The network to do this is shown in the diagram below. 
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PS 300 APPLICATION NOTE #4 



Objeet-Space Rotations 


05LJCmu/c 


DIALS(i) 


DIALS<j > 
180 



IAS0230 


Figure 3-2. Object-Space Rotation Network 


The output of the last function should also be connected to a rotation node in the data 
structure. 


NOTES, EXAMPLES 

There should only be one rotation node in the data structure (not one each for X, Y, and 
Z rotations). This node can be created with the ROTate X, ROTate Y, or RQTate Z 
commands. 

To reset the network and rotation node in the data structure, put an identity matrix on 
input <1> of □5_Rotation. This can be done by connecting an instance of FrXROTATE 
to it and sending a 0 to input <1> of OS Reset. 


o 














PS 300 APPLICATION NOTE #5 


Rational Polynomial Command Usage 


Marty Best, Bill Armstrong 
Systems Engineering 
Evans & Sutherland 
Salt Lake City, Utah 
April 1982 

CATEGORIES: Circles, ellipses, curve generation. Rational Polynomial 
command usage 


DESCRIPTION 

The Polynomial commands that are available on the PS 300 offer a powerful means of 
building curve shapes without transmitting large numbers of vectors. Unfortunately, 
use of the Polynomial commands requires an understanding of curve generation and a 
routine for computing the curve parameters to be sent to the PS 300. Only users 
experienced in curve generation, for the most part, will find a specific use for them. 

Some basic curve shapes, however, can be adapted to many applications and are simple 
to implement. 

The command detailed below can be modified to draw a circle of a given radius, or an 
ellipse of a specified size. Of course, these primitives can be instanced by any other 
structure and translated, rotated, or scaled. 


IMPLEMENTATION 

A circle must be defined in two parts using a Rational Polynomial command. It can 
then be included in a BEGIN_Structure...END_Structure and referenced as a single 
entity. The syntax is as follows: 
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PS 300 APPLICATION NOTE #5 
Rational Polynomial Command Usage 



CIRCLE := BEGIN Structure 

RATional POLYnomial 
2r, 0, 0, 2 

-2r, -2r, 0,-2 

0, r, 0, 1 
CHQRDS=25; 

RATional POLYnomial 
2r, 0, 0,-2 

-2r, -2r, 0, 2 

0, r, 0,-1 
CHORDS=25; 
END_Structure; 


where r is the desired radius of the circle. The number of chords have been set at 25 to 
give a smooth appearance. 


NOTES, EXAMPLES 

The two Rational Polynomial commands given above define the right and left 
semi-circles of the circle and can be made the top and bottom semi-circles by 
exchanging the X and Y columns (Columns 1 and 2). 

The above circle can be modified to give an ellipse as follows: 



ELLIPSE := BEGIN_Structure 

RATional POLYnomial 
2a, 0, 0, 2 
-2a,-2b, 0,-2 

0, b, 0, 1 
CHORD5=25; 

RATional POLYnomial 
2a, 0, 0,-2 
-2a,-2b, 0, 2 

0, b, 0,-1 
CHORDS=25; 
END_Structure; 


where a and b are the major and minor axes of the ellipse. Again the number of chords 
has been chosen for smoothness. 




PS 300 APPLICATION NOTES #6 



Proportional Scaling 


Neil Harrington 
Marketing Support 
Evans & Sutherland 
Salt Lake City, Utah 
September, 1982 


CATEGORIES: Scaling 




DESCRIPTION 


A dial is usually used to accumulate the scale factor in standard scaling networks. It*s 
hard to control scaling this way, though, since the current scale factor becomes very 
small or very large in proportion to the new dial value. For example: 


Current Scale Factor 


New Dial Value New Scale Factor % Increase 


0.01 

100.00 


.1 0.11 1000.0 

.1 100.10 O.l 


When the current scale factor is small, the effect of a turn of the dial is large, and vice 
versa. 


The network shown below will correct this problem by making the effect of the dial 
proportional to the current scaling factor. Using this network the chart shown above 
will look like: 


Current Scale Factor 


New Dial Value 


New Scale Factor % Increase 


0.01 

100.00 


.1 O.Oll 10 

.1 110.00 10 
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PS 300 APPLICATION NOTES #6 


Proportional Sealing 



IMPLEMENTATION 


Prop^Sca/e 



IAS0231 


Figure 6-1. Proportional Sealing Network 
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PS 300 APPLICATION NOTE #7 



Local Inking of Tablet Coordinates 


Neil Harrington 
Marketing Software Support 
Evans & Sutherland 
Salt Lake City, Utah 
June 1982 


CATEGORIES: Inking, F:XOR 
DESCRIPTION 

Inking is the technique of using an input device (usually the data tablet) to sketch 
"freehand.” This application note describes a function network that will allow the user 
to do inking with the data tablet. 



IMPLEMENTATION 

The network is as follows: 

Data structure A should be DISPiayed and be created with a command such as: 

A := VEC n=1000 0,0; 

(The n=1000, or some other number, allocates a block of memory for the vector list). 


TABLETIN 


i 

<i>|- 

!<n 

<2>|- 

i<2> 

(8)1- j- 

'<3> 

<*)!-i 

: i 1 


<9>i— 1 


<«>l— i 


/NK--Togg / 0 

/NfCJ’a/nfs 




r 

- 1 i r—r 

' F:XOR ! -■[- ' 

; ! F:CBROUTE 

ci 

— r^_ 

i ; 

^^ 


/N/CJ^os^ fn« 


I—<APPEND>A 

! 

I /NfCJ. //y» 


i F:POSITION_LINE 


i F:CONSTANT 1 


/N/CJ^as 


A 

--—e- 


F:BROUTEC: 


P'iglire 7-1, Inking Network 
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PS 300 APPLICATION NOTE #7 
Local Inking of Tablet Coordinates 



NOTES 

To use this, press and release the data tablet pen to start inking and then press and 
release it again to stop inking. Do this as many times as needed. 



PS 300 APPLICATION NOTE #8 



Local Rubber-Banding of Tablet Coordinates 


Neil Harrington 
Marketing Software Support 
Evans & Sutherland 
Salt Lake City, Utah 
June 1982 


CATEGORIES: Rubber-banding, grid-banding 


DESCRIPTION 

This note describes a function network to do rubber-banding using the data tablet. 

Rubber-banding is the technique of displaying a line segment that extends from some 
fixed point to the data tablet cursor and moves along with the cursor until some 
indication is given (such as pressing the data tablet pen switch) to fix the line segment 
at the current position. This way you can see the lie of the line before you finish 
positioning it. 

o 

IMPLEMENTATION 

The network is as follows: 

Data structure A should be DISPlayed and be created with a command such as: 

A := VEC n=1000 0,0; 

(The n=1000, or some other number, allocates a block of memory for the vector list). 
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PS 300 APPLICATION NOTE #8 


Local Rubber-Banding of Tablet Coordinates 


TABLBTIN 



IAS0233 


Figure 8-1. Rubber-Baiiding Network 


NOTES 


To use this network, press and release the stylus on the data tablet to fix the first 
position. Moving the stylus around on the tablet now will create a rubber-band line 
from the initial position to the cursor. 

Pressing and releasing the stylus again will fix this line segment, and a new rubber-band 
line will start from this last point to the next point you press down on and so on. To 
break this continuous line and start a new series of rubber-band segments, you must 
move the stylus away from the tablet surface. This will cause the current rubber-band 
line to disappear; a new one will start as soon as a new starting position is selected. 
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PS 300 APPLICATION NOTE #9 


Local Grid-Baiidiiig of Tablet Coordinates 


Kerry Evans 
Systems Engineering 
Evans & Sutherland 
Salt Lake City, Utah 
April 1982 

CATEGORIES: Grid-banding, rubber-banding, function networks, data tablet 
DESCRIPTION 

This note describes a function network which takes 2D coordinates from the data tablet 
and constrains the points to fall on grid points of a user-defined grid — that is, it 
performs rubber-banding to discrete points on a grid. We call this grid-banding (see 
also Application Note #8.) 


IMPLEMENTATION 

Use the same network as that for rubber-banding (Application Note /f8), but instead of 
connecting the tablet xy position (TABLETIN <1>) to the POSITION_LINE Function 
directly, connect the output of the DIVC Function in the network shown below to the 
POSITION_LINE Function. 

Specify the number of grid-points per unit by sending a real to input <1> of the NGP 
function. For example, sending 10 causes the vectors output from the DIVC function to 
lie on grid-points O.l unit apart in X and Y. 



Figure 9-1. Grid-Banding Network 
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PS 300 APPLICATION NOTE #9 


Local Grid-Banding of Tablet Coordinates 



NOTES, EXAMPLES 

Use just like rubber-banding (Application Note #8). This is an easy way of doing 
rubber-banding without having to be as accurate with pen positioning, especially if 
you're doings things like schematics or block diagrams. 
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PS 300 APPLICATION NOTE #10 


Translation Network 


Kerry Evans 
Systems Engineering 
Evans & Sutherland 
Salt Lake City, Utah 
April 1982 

CATEGORIES: Translation, FrACCUMULATE 
DESCRIPTION 

This application note shows an example of how the ACCUMULATE function may be 
used to build translation vectors from the dials. Since ACCUMULATE can accept real 
numbers or vectors, it is a simple matter for it to accumulate "position.** 



IMPLEMENTATION 

The following function network allows Dials 1, 2, and 3 to control the X, Y, and Z 
components of the Translate vector, respectively. 


Tran^ 


DIALS<1>— 

F:XVECT0R —^ 



Tran^Y 


DIALS<j>— 

FrYVECTOR |— 



Tran^ 


DIALS<k>—; 

F:ZVECT0R —' ! 


Transia f9 


Initial position or reset -—1<2> 

Minirrun change in position per output -1<3> 

Scale factor for input 1 (Real or V3D)—<*y 

Upper limit (Real or V3D) -^<®> 

Lower limit (Real or VSRJ - 


F: ACCUMULATE 




-{1) (Translation data node) 
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Figure lO-l. Translation Network 







PS 300 APPLICATION NOTE #10 


Translation Network 


NOTES, EXAMPLES 

The X, Y, and Z vector functions build 3D vectors from the dial values, which get 
scaled by input <4> of ACCUMULATE and accumulated on input <2>. ACCUMULATE 
may be reset by sending the initial translation value to input <2>. But no output will be 
generated until input is received on <1>. This may be the result of turning a dial or 
sending a Boolean value to <1>. 

Scale factor and upper and lower limit may be real numbers (if uniform scaling and 
limiting in X, Y and Z is desired) or they may be vectors, in which case the components 
are applied individually in each dimension. Input <3> specifies the amount by which the 
accumulated sum must change before an output is generated. This amount is a real 
number greater than or equal to 0. 






PS 300 APPLICATION NOTE #11 
Animation Sequencing with CLOCK Function 


Gary Cannon, Neil Harrington 
Marketing Support 
Evans & Sutherland 
Salt Lake City, Utah 
May 1982 


CATEGORIES: Animation, FrCLCSECONDS 


DESCRIPTION 

This shows a method for using a series of clock functions (FrCLCSECONDS, 
FrCLFRAMES, and/or FrCLTICKS) to run through a sequence of actions. 


IMPLEMENTATION 

A clock can control some motion for a given time span, then stop and trigger the start 
of the next clock in sequence, which controls some other motion. 
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Figure ll-l. Animation Sequencing On-The-Fly 


- 31 - 









PS 300 APPLICATION NOTE #11 


Animation Sequencing with CLOCK Function 



NOTES, EXAMPLES 

The actions best suited for this type of animation sequence are those that can use the 
summing outputs <1> or <2> to modify the currently displayed data structure. An 
example of this would be using output <2> to feed a rotation network that then modifies 
a rotation node in the displayed data structure. 

When output <3> of the clock generates a FALSE, a network could also be triggered to 
change the level of detail and change the data structure being viewed. 

To cycle repetitively through the sequence, input <2> of each of the timers needs to be 
reset to the initial value. This could be done by having the NOT function of the last 
sequence trigger the following network (note that this network will also trigger the 
sequence to start over again **n** times). 


S0au*ne0^0sm f 



n - Nunbtr of Urmra 
m - of tMnrmt to r«cyel« 

i,t. .i" - Duration of «ao^ tiromr 
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Figiu-e 11-2. Animation Replay and Reset Network 






PS 300 APPLICATION NOTE #12 


Frame-by-Frame Animation 


Neil Harrington 
Marketing Support 
Evans & Sutherland 
Salt Lake City, Utah 
August, 1982 


CATEGORIES: Animation, F:CLCSECONDS, F:MODC, Level of Detail 


DESCRIPTION 

This shows a method for using a clock function (F:CLCSECONDS, FtCLFRAMES, or 
FtCLTICKS) to cycle through a series of previously calculated frames. Typically, each 
frame would consist of different transformations applied to the same objects. The 
modulo function allows for the animation to recycle indefinitely. 


IMPLEMENTATION 


An Inxit ton 
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Figure 12-1. Frame-by-Frame Animation 
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PS 300 APPLICATION NOTE #12 


Frame-by-Frame Animation 


NOTES 

1. Input <1> of Frame Timer could be dynamically altered to change the speed of the 
animation sequence. 

2. Input <4> of Frame_Timer could be dynamically altered to skip frames in the 
animation sequence. 

3. The clock could be stopped and a value sent to input <1> of Frame Modulo to look 
at a particular frame in the sequence. 
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Menu Selection 


Gary Cannon 
Marketing Support 
Evans & Sutherland 
Salt Lake City, Utah 
August, 1982 


CATEGORIES: Menus 

DESCRIPTION 

This function network allows you to do menu picking from a defined menu in a specific 
area of the screen. It uses simple math to produce a "box number" from the tablet x 
and y coordinates. 

The menu boundaries are shown below as they would appear in a full screen viewport on 
the screen: 





IAS0240 

Figure 13-1. Menu 
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Menu Selection 



Each of the numbers shown is a value produced by the network when the screen cursor 
is in the menu box with that number and the stylus is pressed down on the tablet. Of 
course, these numbers should be replaced by descriptive names for the real menu. 


IMPLEMENTATION 

The menu selection network is shown below: 



Figure 13-2. Menu Selection Network 


NOTES 

With modifications to this network, menus of other sizes and shapes can easily be 
created. 
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Rotary Switch 


Carl Ellison 
Software Engineering 
Evans & Sutherland 
Salt Lake City, Utah 
August 1982 


CATEGORIES: Switching, Multiplexing, F:SYNC(n), FiSWITCH 
DESCRIPTION 

The simplest form of multiplexing breaks a stream of items into a collection of streams 
by sending the first item to destination 1, the second to destination 2..., the nth to 
destination n, the (n+1) back to destination 1, and so on. As long as n<=20 the function 
network shown below can do that job. 



IMPLEMENTATION 
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Figure 14-1. Rotary Switch Network 
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Shift Register 


Carl Ellison 
Software Engineering 
Evans & Sutherland 
Salt Lake City, Utah 
August, 1982 


CATEGORIES: Shift register, F:SYNC(n) 

DESCRIPTION 

F:SYNC(n) can be used to act as a shift register. It can be used, for example, to 
achieve scrolling by feeding character strings to CHARACTER display nodes. 

IMPLEMENTATION 
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Figure 15-1. Shift Register Network 



NOTES 

These FrSYNC functions could be cascaded to shift or scroll more than 20 lines if 
needed. 
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Function Network Sequencing 


Carl Ellison 
Software Engineering 
Evans & Sutherland 
Salt Lake City, Utah 
August, 1982 


CATEGORIES: Function network sequencing, F:SYNC(n), function loops, 
synchronization 


DESCRIPTION 

This application note describes how to control when a function network, or series of 
networks, runs. The sequencing schemes described here are based on the use of a "GO" 
token which is passed around among F:SYNC(n) functions, controlling the activation of 
sub-networks. 

This type of network implementation can be safer, also, since it will not allow new 
tokens into a network until it has completely processed the current tokens. 


IMPLEMENTATION 

The network shown below has its inputs and outputs controlled by F:SYNC(n) functions. 
This allows the network to "execute" completely before accepting new inputs: 
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; F:SYNC(J+1) 
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Figure 16-1. Function Network Sequencing 


The network shown below shows an arbitrary number of sub-networks linked together. 
This forces the sequential processing of these networks. 
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Function Network Sequencing 




IAS02U4 

Figiu“e 16-2. Sequential Executing Networks 
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D 

^ IF-THEN-ELSE Construct 


Carl Ellison 
Software Engineering 
Evans &. Sutherland 
Salt Lake City, Utah 
August, 1982 


CATEGORIES: IF-THEN-ELSE, Boolean switch, FiSELECT 



DESCRIPTION 

This application note shows how to implement an IF-THEN-ELSE construct using 
PS 300 functions. It assumes **i** values are input to test some Boolean relation. The 
values are then routed to one of two networks depending on the Boolean value that is 
output from the expression. This implementation is similar to the general programming 
statement: 

IF <expression> THEN statementl 
ELSE statement?; 


o 
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IF-THEN-ELSE Construct 



IMPLEMENTATION 


Input 
Var IabI 




Figure 17-1. IF-THEN-ELSE Network 


NOTE 

This application shows how F:5ELECT can be used as a Boolean switch function. 
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PS 300 APPLICATION NOTES #18 
A Real-Time Analog and Digital Clock 


Patrick Fitzhorn, David Ferguson 

Center for Computer-Assisted Engineering 

Colorado State University 

Ft. Collins, Colorado 

October, 1982 


CATEGORIES: FrCLTICKS 


DESCRIPTION 

Frequently it is useful to display a real-time clock on the PS 300 screen. The network 
described here has, as an end result, both an analog clock component (rotations in 
degrees for the hour, minute, and second hands) and a digital component. 


o 


IMPLEMENTATION 

The network is based on FiCLTICKS with constant input of 120 on input <1>. This 
generates an integer at output <2> once per second, which is incremented by one each 
tick. The clock is based on a 12-hour cycle, so F:MODC resets the clock after 43,200 
seconds. 

An initialization network is provided that changes standard hour, minute, and seconds 
input into seconds. This value is then sent to input <5> of FrCLTICKS, which serves as 
a new starting value for the clock. The network diagram is on the following page. 
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A Real-Time Analog and Digital Clock 
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Figure 18-1. Clock Network 
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A Real-Time Analog and Digital Clock 


An example of the data structure for the analog clock face is: 


ANALGG CLOCK := BEGlN Structure 

VIEWport HORizontal=-. 1 :.545A \/ERtical=-l:l; 
SEGONDS := ROTate 0 := THEN SECOND HAND; 

MINUTES := ROTate 0 THEN MINUTE HAND; 

HOURS := ROTate 0 THEN HOUR_HAND; 

ENDStructure; 

SECOND HAND := SCALE .025,1 THEN BASIC HAND; 

MINUTE_HAND := SCALE .05,.8 THEN BAS1C_HAND; 

HOUR_HAND := SCALE .075,.5 THEN BASIC_HAND; 

BASIC_HAND := VECtorJist N=5 0,0 1,.25 0,1 -1,.25 0,0; 
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A Real-Time Analog and Digital Clock 


NOTES 

The digital clock’s display is of the form: (hours):(minutes):(seconds) with a maximum 
of eight digits. 

The output can be connected to a character node in a display data structure or to a 
function-key LED label, if so desired. In the current digital component, leading zeros 
for minutes and seconds do not appear, so that 9:05:05 is displayed as 9:5:5. This has 
not proved to be much of a hardship. If a standard 8-digit output is required, one could 
test the minute and second outputs and, if less than 10, concatenate a leading zero. 

The clock starts out at time 00:00:00. To set the clock, the following commands are 
used: 



store fix(h) to <l>hours 

store fix(m) to <l>minutes 

store fix(s) to <l>seconds 

where 

h = integer between 1 and 12 

m, s = integer between 1 and 60 
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LIMITED SUPPORT DISCLAIMER 

This software package is distributed by Evans & 
Sutherland as a convenience to customers and as an aid to 
understanding the capabilities of the PS 300 graphics 
systems. Evans &. Sutherland Customer Engineering 
supports the package to the extent of answering questions 
concerning installation and operation of the programs, as 
well as receiving reports on any bugs encountered while 
the programs are running. However, Evans & Sutherland 
makes no commitment to correct any errors which may be 
found. 
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PREFACE 


This document is the user's guide which accompanies the Function Network Editor 
program, NETEDIT. The Function Network Editor is run on the PS 300 to create 
function networks as diagrams. When the diagram is complete, an ASCII code file can 
be generated directly from the diagrams. 

This manual explains how to run NETEDIT and how to install it under VAX/VMS 3.3. It 
is divided into the following sections. 

Section 1 is an overview of the Editor. It explains how network diagrams are structured 
and gives a general orientation to using the Function Network Editor. 

Section 2 explains how to run the Editor from a command file menu and how to restart. 

Section 3 describes the basic features of user interaction and display organization and 
other characteristics of the Editor. 

Section 4 describes the placement, movement, and deletion of the objects and 
connections which make up a diagram. 

Section 5 describes file control, moving between different files during an editing 
session, and recovering from crashes. 

Section 6 describes the conversion of a diagram file into an ASCII PS 300 file. 

Appendix A describes how to install the system under VAX VMS 3.3., how to customize 
the command menu files, and how to set up a parameter file. 

Appendix B describes a sample editing session to create a small network. Illustrations 
are included to show the network diagram at various stages of editing, and the final 
ASCII code file is listed. 
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1. INTRODUCTION TO THE FUNCTION NETWORK EDITOR 


The NETEDIT Function Network Editor is a program to aid in the creation of PS 30Q 
function networks. Networks are created as diagrams using a drawing program with 
menu selections. Symbols representing functions are placed in the diagram and their 
inputs and outputs are connected much as in a wiring diagram. Constants and variables 
can be specified. Items can be named and annotations can be added freely. When the 
diagram is complete, the Editor allows you to generate an ASCII file of the 
corresponding PS 300 commands and comments. Hardcopies of diagrams can be 
obtained if the PS 300 system has the Hardcopy Option. 


USING THE EDITOR 


The Network Editor currently runs under VAX VMS 3.3 and higher, uses Pascal 
V2.2 and higher source code, and uses version P5.V03 and higher of the PS 300 
firmware. Files are distributed on magnetic tape and are installed as explained 
in Appendix A. 

Command files display menus which let you start the Editor and restart if a 
crash occurs. A log file is kept each time the Editor is started and this is used in 
recovery. A parameter file can be created to specify user-definable options, 
such as directory names and file extensions. 


EDITING A FILE 


NETEDIT stores the diagram as a hierarchical data structure in a sequential 
file. It allows single files to represent extended function networks with external 
contact points to other function networks or nodes in a display structure. It also 
allows you to use macros (references to libraries of other networks) and 
user-written functions. 


o 



2 - FUNCTION NETWORK EDITOR 


You edit a file by making menu selections with the data tablet or in some cases 
with the Function Keys. Selections let you place items in the display area to 
create the network drawing, or change the drawing as needed. Other selections 
display HELP information, access other files, and generate ASCII code from the 
network diagram. 


Network Diagram Primitives 


Intrinsic functions, initial function instances, user-written functions, and macros 
are represented as boxes with numbered inputs and outputs. Functions are 
selected and placed in the display area and named using the Labels selection. 
This results in name F:Function_name; statements in the ASCII file that is 

generated. 

Connections corresponding to CONNECT name<i>: <j>name; commands are made 
by routing arcs from one connection point to another. Connecting arcs are 
shown as lines much like wires in a wiring diagram. A connector is and arc 
endpoint. It may be an input queue to a function and so part of the function box, 
or one of several free-floating types of endpoints. 

Constant connectors can be placed in the diagram and connected to function 
inputs. The value associated with the constant is entered also. This results in 
SEND value TO <i>:name; statements in the final ACSII file. 

Variables are created as connectors also. These correspond to instances of the 
VARIABLE namel] command. 


Constructing the Diagram 

Since the display area is limited and networks are often quite extensive, most 
diagrams will be broken up into pages. The Editor allows you to construct a 
diagram hierarchically by creating a "frame” for each page and by letting you 
create "detail frames”, which represent lower pages in the hierarchy. 

Detail frames are shown as pseudo-3D boxes with inputs and outputs. They 
represent different functional blocks of a network. For example, the parts of a 
network which handle input from the dials can be shown as a detail frame within 
a page that shows a general network of peripherals and display manipulation. 
When you move into that detail frame the actual functions which comprise the 
detail will be shown. Details can be nested to any level. 






FUNCTION NETWORK EDITOR - 3 


The hierarchical nature of the network diagram means you can create a network 
top-down or bottom-up. Detail frames can be created first and then their 
contents can be specified later or parts of the diagram can be moved into or 
deleted from detail frames. The diagram can be constructed and restructured 
however you want. You navigate between frames using function keys. 


Generating the PS 300 Command File 


When the diagram is completed, selections from the menus allow you to generate 
an ASCII file of PS 300 commands which instance the functions, connect inputs 
and outputs, declare variables, and send data as shown in the diagram. 

A sample ASCII file generated by the Editor is included in Appendix B. 
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2. GETTING STARTED 


The Network Editor is started and entered through menu selections displayed by a 
command file. After the Network Editor and associated files have been installed and 
the command files NETUSER.COM and NETBUILD.COM have been customized by the 
system manager, enter the following command. 

$ @[HomeDir]NETUSER 

For [HomeDir], substitute the name of the directory in which NETEDIT resides. This 
command file brings up the following Initial Menu. 



Evans &. Sutherland PS 300 Utilities \/1.06 
Initial Menu 


0) Exit 

1) Initialize the PS 300 

2) Send a file to the PS 300 

3) Run NetProbe - Function Network Debugger (Menu) 

4) Run NetEdit - Function Network Editor (Menu) 

5) Character Font Utilities (Menu) 


Select option 4 to bring up the following NETEDIT Menu of options specific to running 
the Network Editor. 


Evans & Sutherland Function Network Editor 
Maintenance Command File VI.06 

NetEdit: PS 300 Function Network Editor Menu 



0) Exit 

1) Start NetEdit from scratch, download support net 

2) Start NetEdit without full init, but download support net 

3) Restart NetEdit without downloading support net 

4) Read the current release notes 

5) Start NetEdit without full init from floppy disk 

6) Init from floppy 
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Selection 1 initializes the PS 300 and loads NETEDIT. This is the selection most often 
made when the Editor is run. Selection 2 loads NETEDIT without initializing the 
PS 300. Selection 3 restarts the Editor after a crash or an aborted session. Selection 4 
lets you review the current release notes. Selection 5 allows you to load NETEDIT from 
a floppy diskette. Selection 6 initializes the PS 300 from a floppy diskette. This must 
be done if NETEDIT was loaded from a floppy diskette. 

To start NETEDIT for the first time, use selection 1 or 2. When the Editor display 
appears, pick SELECT NETWORK and you will be prompted for the name of the file you 
want to edit. 

A sample editing session is included in Appendix B. You may wish to glance through 
this before reading the following chapters. 


RESTARTING 


Should the program crash while you are editing or should you deliberately abort 
the current session using Control-C, the network editor may be restarted 
without reloading the support network and display structures by using the menu 
selections or typing the following command. 

$ §[HomeDir]NETUSER 4 3 

For [HomeDir], substitute the name of the directory in which NETEDIT resides. 
The parameters 4 3 make the menu selections for you. Note that all selections 
from the command file menus can be given as parameters to bypass the menu 
displays. 



PARAMETER FILE 


A parameter file permits each user to customize the Editor by describing a 
working set of directories and selecting some options. 

Create a parameter file called NETPARMS.TXT. In this file, list the directories 
(up to 30) that you want to have in your working set. List them in order of 
preference, since the directories will be searched in this order. 
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The parameter file can also contain 
these consist of the following. 

©EXTENSION .FUN 

©SYSTEMPRIVILEGE 

©COLOR ON/OFF 

©FIRMWARE P5.V03 
©PRIMITIVEPROMPT ON/OFF 


other operating parameters. Currently, 

This sets the ASCII output file extension 
to .FUN, and may be changed to any 
other extension. 

The Editor is set by default to use the 
user/primitive function data base but 
may be changed to use system privileged 
functions. 

Enables and disables color when 
displaying the Editor on the CSM. If you 
are using the CSM, turn color on. 
Objects will be colored and the cursors 
will be white. 

Tells NETEDIT that a non-Al firmware 
diskette is being used. 

Enables/disables prompting for function 
names immediately as they are instanced 
and placed. 


The parameter file is expected to reside in the directory NETUSERDIR. You 
must make this logical assignment either manually or by inserting the following 
line into your login or similar file. 

©ASSIGN [UserHomeDir] NETUSERDIR: 

[UserHomeDir] should be replaced with the directory in which you keep your 
parameter file. This ensures that the Editor can find your parameter file from 
wherever it may be run. 


o 
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3. GENERAL CHARACTERISTICS 


DISPLAY ORGANIZATION 


O 


The Editor display is divided into three sections. 

The main section is the diagram DISPLAY AREA in which you assemble and edit 
the network diagram. This is made up of two parts: a header bar, which 
describes the frame, and a work area in which you can pan and zoom. 

The header bar includes the name and prefix of the current frame, the file name, 
a page number, the total number of pages, and the date the file was last 
modified. The name and prefix in the header can be modified by picking the 
item from the bar and entering a new value. The header bar is unaffected by 
panning and zooming. 

The work area is an oblong of a size which allows hardcopy to fit neatly on 8 1/2 
by 11 inch paper. Panning and zooming using the Control Dials can be performed 
in the display area. 

On the right edge of the display is the MENU AREA in which the different Editor 
menus are displayed. Up to three menus may be present at a time, depending on 
where you are in the hierarchy of menu options. 

At the bottom of the screen is the MESSAGE AREA, two lines in which messages 
are displayed. The top line serves as a PROMPT and text entry line, and the 
second line displays warning and STATUS messages. The abbreviations I - 
information, W - warning, E - error are used to indicate the relative severity of 
the message. 

Figure 1 shows the initial Network Editor display. 


o 
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Figure 1. Function Network Editor Display 




The VIEWMENU function key (Function Key 1) is used to alternate between the 
diagram/menu display for editing and the diagram only for hardcopy and closer 
inspection. 
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The HELP and HISTORY selections also change the display. When these 
functions are chosen, the display is as shown in Figure 2. 


Evans 8. Sutherland PS300 Function Network Editor VI. 06 
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Figure 2. The HELP and HISTORY Display 
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CURSOR SHAPES 


You interact with the display through a combination of tablet and keyboard 
actions. The cursor shows not only the current location at which you are 
pointing but also the current state of the program by changing shape for 
different actions. The most basic cursor shapes indicate when only a menu 
selection is permitted (a chevron), when no action is yet permitted (hourglass), 
when keyboard entry is permitted (downward pointing hand), and when an object 
may be placed, moved, or deleted (various shapes). A clock shape with sweeping 
arm appears for extended periods of waiting. This will help you judge the 
progress of the operation. With most cursor shapes, an asterisk (*) indicates 
exactly what point on the shape is the pen tip, which is the point at which object 
or menu **picking*' is performed. Where an asterisk is not present, as with the 
arrow cursor shapes, the tip of the arrow corresponds to the point of the pen. 
Cursor shapes are described in the course of the documentation as appropriate. 
An optional cross-hair may be displayed at the cursor positioning by toggling 
Function Key 2. This cross-hair is useful for aligning objects on the display. 


MENU SELECTIONS 


The control and object menus are divided into three menus: the PERMANENT 
MENU (FiELP, EXIT, HISTORY); the MAIN MENU (editing selections and further 
options); and the SUBMENU (object categories, file options) which will appear as 
needed. The permanent menu is always present and may always be selected 
from. When a permanent menu option has been invoked that option is 
highlighted. All cursor shapes except the hourglass or clock may be used to 
select from the menu at any time. Any incomplete action is canceled by making 
another selection. This includes keyboard entry and object placement. 

The main and submenus are arranged as a hierarchy which will sometimes display 
two different levels (MAIN and SUBMENU) and at other times just one (MAIN). 
You move from menu to menu by picking selections with the data tablet and pen 
or pressing certain function keys. The first item in all but the top level menu is 
in capital letters and preceded by a chevron (^) to signify that it is both the title 
of the menu and the entry point to move up. Selecting it will reset the menu 
display accordingly. Many submenus are particularly long. When a submenu is 
displayed it may be scrolled up or down by means of the first dial on the control 
dials unit. At the bottom of the submenu is a long string of dashes to indicate 
that you have moved off the bottom and that you should scroll upwards to find 
the submenu. 
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The menu hierarchy is as follows. 

HELP 

EXIT 

HISTORY 

FILE CONTROL 

SELECT NETWORK 
BACKUP NETWORK 
SCRATCH NETWORK 
RECOVER 

RENAME NETWORK 



EDITING 

ADD ITEM 

Detail Frame 

Functions 

Connector 

Input Frame 

Output Frame 

Constants 

Variable 

In-External 

Out-External 

Arc 

Labels 

MOVE 

MOVE AREA 
DELETE 
DELETE AREA 
OPTIONS 

Change Scale 
Redraw Frame 
Replace Functions 
Update Macros 
Print Page 
Print Page Set 

CONVERT NETWORK 
ASCII OUTPUT 
USE FRAME PREFIX 
USE MACRO PREFIX 
COMPILE MACRO 
SUPPRESS COMMENTS 
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PERMANENT MENU ITEMS 


HELP 

The HELP selection provides information on individual functions, all menu 
selections, and a variety of other topics. To get information on menu selections, 
select HELP and then pick the menu item. To get help on a function, pick 
EDITING, then ADD ITEM, then Functions, and pick the name of the function 
you are interested in. The scrolling dial. Dial 3 can be used to scan forwards and 
backwards through long descriptions. 


EXIT 

EXIT saves any existing network that has been edited, closes all open files, 
returns the keyboard to terminal emulator mode, and exits from the program. If 
the file name is incorrect, EXIT will not let you leave the program. When this 
occurs, you must either scratch or rename the network and select EXIT again. 
Note that EXIT must be picked twice before it is selected. 



HISTORY 

This selection allows you to view the last ten pages of status messages. This can 
be useful when a code conversion produces errors and the messages have moved 
past faster than they could be read. The scrolling dial, Dial 3 can be used to 
scan forwards and backwards through the pages. 


FUNCTION KEYS 

Currently, 11 of the 12 function keys are programmed to perform specific 
operations. Most keys perform only one function, but keys 8, 9, and 10 have 
double functions. The keys are programmed as follows. 


Key 1 - VIEWMENU 

Changes the display for closer inspection and for hardcopy of diagrams. 
Removes the MENU area and MESSAGE area and displays just the diagram at 
a size that produces 8 1/2 by 11 inch hardcopies. 
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Key 2 - CROSS 

Displays a cross-hair to help you place objects in the diagram. 

Key 3 - GO UP 

Moves you up one level in the diagram hierarchy from the current frame 
(context) to its parent frame. The frame you were just in appears as a detail 
frame in the new display. You are notified if you are in the top frame and so 
are unable to go higher. 


Key A - OUTLINE 

Displays a page which shows the structure of the diagram file. All frames in 
the file are listed, and indentation shows the hierarchical dependencies. The 
frame currently being edited is highlighted. The outline can be scrolled using 
Dial 2. You may also pick a frame in the outline and proceed directly to that 
frame without going through the intermediate frames. 



Key 5 - GO DOWN 

Moves you into a detail frame in the context frame you are currently 
editing. If more than one detail frame is present, a large down-pointing 
arrow is displayed to allow you to select the detail fran^e you want to enter. 


Key 6 - FULL VIEW 

Resets the display after zooming and panning has taken place with the 
control dials. 


Key 7 - BY NAME 

Allows you to select an intrinsic function, initial function instance, macro, or 
user-written function by name. Press this key and then enter the name at 
the PROMPT line at the bottom of the screen. For primitive functions, you 
may place multiple copies before selecting another primitive. For macros 
and user-written functions, you are prompted after each placement. 


Key 8 - MOV/E (double function) 

Allows you to select MOVE or MOVE AREA without picking from the menu. 
One press selects MOVE, two presses select MOVE AREA. 



Key 9 - DELETE (double function) 

Allows you to select DELETE or DELETE AREA without picking from the 
menu. One press selects DELETE, two presses select DELETE AREA. 
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Key 10 - ARC/TEXT (double function) 

Allows you to place an arc or edit labels without picking from the menu. One 
press selects ARC, two presses select LABELS. 


Key 11 

This key is currently unused. 


Key 12 - CANCE L 

Allows you to cancel a hardcopy from the plotter. 


CONTROL DIALS 

The Editor uses 6 of the 8 Control Dials to help in building and viewing network 
diagrams. The dials are programmed as follows. 

Dial 1 - SUBMENU 

Scrolls a submenu up and down. 


Dial 2 - OUTLINE 

Scolls the diagram outline page forwards and backwards. 



Dial 3 - FLIPPAGE 

Scans forwards and backwards through HELP or HISTORY pages. 


Dial 4 

This dial is currently unused. 


Dial 5 - ZOOM 

Zooms in and out of the diagram. 


Dial 6 - HORIZNTL 

Pans left and right in the diagram after zooming. When panning, you cannot 
move out of the diagram work area. 


Dial 7 - VERTICAL 

Pans up and down in the diagram after zooming. Again, you cannot move out 
of the diagram work area. 


Dial 8 

This dial is currently unused. 
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TEXT 


There are two types of text used in a network diagram: permanent text and 
notations. Any textual information which is in italics on the diagram may be 
altered interactively by using the ADD ITEM/Labels selection. Any text shown 
in the standard font is permanent. When you are prompted for text entry (the 
downward pointing hand), either type in the string you want followed by a 
carriage return, or select another menu item to change your mind. Any text 
entered but not followed by a return will have.no effect on the display or current 
status. 


MACROS 


Macros are a means of incorporating into a network file code which is described 
in another file. They may be referenced repeatedly in the same file and may be 
nested to any level. When a macro is instanced, it appears in the diagram 
exactly as a function would, except that the name is preceded by M: instead of 
F:. Any existing network file that has been created by the Editor can be 
referenced as a macro. The macro description is derived from the top level 
frame of the network file, using the list of directories set up in your parameter 
file. 


Instancing Macros 

To instance a macro, use the BY NAME function key just as you do for selecting 
a primitive function but enter the file name of the source network file instead of 
a function name. If the name does not conflict with an existing primitive 
function, the editor will try to find the file. 


Compiling and Prefixing 

Macros must be compiled using the Compile Macro option of the menu selection 
CONVERT NETWORK. Macros may be prefixed with the Use Macro Prefix 
option to distinguish multiple uses of the same macro. Compiling a macro 
produces a .MAC file, which may be incorporated into the code for another file 
with proper instancing and connections made. 
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Prefixing Constants, Variables and External References 

Since final names of variables and so on may not be known until the final level 
code conversion, you can flag constants, variable names, and external references 
to indicate where prefixes should be placed as needed. By adding \M\ at the 
beginning of the name within the string, the macro prefix will be added as 
needed in place of it, but no frame prefix will be included. By adding \F\, both 
macro and frame prefixes will be added. 


Date Checking 

Each macro instance is flagged with the date that the source file was last 
modified. This allows the Update Macro option to check against the original 
source file for changes. Macro code which is compiled is flagged with the last 
date the source file was edited and the date that the code was compiled. A 
warning is given during code compilation if the .MAC file was generated from a 
different version of the source file than it was instanced from. The Updating 
Macros selection brings the instance into agreement with the source file, and 
recompiling brings the macro code into agreement with the source file. 



USER-WRITTEN FUNCTIONS 


User-written functions are referenced as if they were macros. The name of a 
user-written function is indicated on the diagram as IJiname^ even though it is 
instanced in the code as F:name. If a network file contains no arcs, primitives, 
or detail frames, then it is automatically assumed to represent a user-written 
function. This allows you to create a description of the user-written function 
with named inputs, outputs, and internal comments which can later be used as a 
help item on that function. No macro code need be compiled for user-written 
functions, since they generate instances exactly as primitive functions do. 
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4. EDITING 


ADD ITEM 


D 


The ADD ITEM selection allows objects to be placed into the diagram space to 
construct a diagram. Generally the object appears at the cursor shape and is 
placed by pushing down the pen when it is in the desired location. The asterisk 
shows where the pen tip actually is. To “discard” the object that you are moving, 
merely select another menu item. Note that while objects are seen completely 
before they are placed, they will be clipped against the boundary of the display 
space once placed. 

The ADD ITEM selection offers the following options: Detail Frame, Functions, 
Connector, Arc, and Labels. 



Detail Frame 

A frame is a portion of the hierarchical representation of the diagram, 
equivalent to a “page" of the complete network diagram. There are two types of 
frames: the one you are in (context frame) or a subsidiary frame within the 
context frame which refers to a lower level of the diagram hierarchy (detail 
frame). A context frame is a diagram page and the program may handle up to 
100 frames within a file, though this may be an impractical size for memory and 
load/save speeds. 

Context frames are bounded by a box outline corresponding to a higher level 
detail frame box. You can place Input Frame or Output Frame connectors on 
this outline in the context frame to create connection points between the 
context frame you are working in and the higher level detail frame which 
references it. Each context frame has a PREFIX (upper left-hand corner) which 
can be changed one level higher on the detail frame representation. The prefix 
is (optionally) used before the function names to maintain unique naming 
between frames. The prefix can be edited in the current frame by picking the 
prefix in the header bar while in Labels mode. Each context frame also has a 
NAME which is used to provide a more descriptive identifier while editing. 
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Frames are created in two ways. When a new file is created, the top level frame 
is created at the same time. From there on, the ADD ITEM/Detail Frame 
selection will add a symbol for the detail frame and also create the 
accompanying frame. 

Detail frames are displayed as pseudo-3D boxes to indicate that they include 
more detail at a lower level. Initially all detail frames have 0 inputs and outputs 
and are created as a minimum size detail symbol. As connectors are added in 
the corresponding frame below, the detail symbol will be updated to reflect its 
new description. The detail frame includes a single line label which may be 
edited exactly as a function box label. 

Input/Output Frame connectors may be attached to the left and right edges of 
the context frame (outside box), respectively. They may later be moved or 
deleted as needed, at which time the detail and its attached arcs will be 
modified as needed. 

Before a frame can be deleted, you are asked to verify the delete. Then the 
frame is deleted along with all contained detail frames and objects. 

To move between frames, there are three function keys: UP, DOWN, and 
OUTLINE. UP will reset the current context frame to the parent of the one you 
were just working in. Since there is only one parent currently allowed, this is 
unambiguous. DOWN will move into a detail frame in the current context. If 
there is more than one, a large down pointing arrow will appear to allow you to 
select the desired detail frame. By hitting the OUTLINE function key, an outline 
page will appear for selecting any frame in the current file; indentation indicates 
the tree structure of the file. The frame currently being edited will be 
highlighted. The outline is implemented as a page in the diagram and may be 
scrolled using Dial 2. 


Functions 

A function is an intrinsic function or initial function instance supported by the 
PS 300 Command Language. When the menu item Functions is selected, a 
submenu of function classes appears, organized by class. Since the list of classes 
is long, some are off the bottom of the display and may be seen by turning the 
dial marked SUBMENU to scroll up and down. When a class is selected, its list of 
functions will appear in place of the class submenu for selection. When a 
function is chosen, its box representation will appear. 
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A function may also be selected by name. This may be a faster method for many 
sessions. Press the BY NAME function key (Key 7) and you will be prompted for 
the name of a function. After the name is entered, the function box will appear 
and may be placed. The same box will appear at the cursor after one has been 
placed, and may be placed as often as needed. 

You must enter the complete name of the function. For *'n" type functions such 
as F:SYNC(n), you are prompted for the number of outputs. 

The BY NAME key can also be used for instancing macros and user-written 
functions. Unlike intrinsic functions or initial function instances, only one 
instance of the macro or user-written function.can be placed at a time. After 
one instance is placed, you are prompted for another name. 

A function consists of a box; a set of up to 50 inputs, which appear on the left 
edge; a set of up to 50 outputs; the name of the function 
type (F:function_name) on the top half of the box, and a user label, initially 
assigned by the system as Pn, written in italics. For initial function instances, 
there is no user label and the function 

name appears as TABLETIN^ or whatever. This user label may be altered 
interactively at any time (see Labels below). Long names are broken at an 
underscore if one is present in the name. 

The function box should be placed within the context frame. At any point that 
arcs are being drawn, the function’s inputs and outputs will be activated for 
picking as appropriate. 

The PRIMITIVEPROMPT OR/OFF option in the parameter file NETPARMS.TXT 
can be set to enable or disable prompting for function names immediately as 
they are instanced and placed. 


Connector 

There are various types of connectors, but all are basically similar in function to 
the primitive inputs and outputs. They serve as the source or destination of an 
arc, which establishes a data path between two points. Currently there are the 
following types of connectors: Input Frame, Output Frame, Constant, Variable, 
In-External, and Out-External. 

The connector shapes are indicated by the direction of the arrow and a contained 
letter (C for Constant, V for Variable, E for External) and may be freely placed 
anywhere in the diagram. For connectors containing text, you will be prompted 
for an initial value and then a copy of the shape and the value will be fixed at 
that location. 
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Input Frame 

Input Frame connectors are attached to the left-hand side of the surrounding box 
outline in the frame and represent input to the frame. When you select a frame 
connector, you are prompted for a name. If you press return, the system will 
assign a number to the connector. This can be changed using the ADD 
ITEM/Labels menu selection or Function Key 10 (TEXT). Names will be 
reflected in the detail frame above as soon as you have finished adding them and 
moved on to another action. Up to 50 of these may be placed. 


Output Frame 

Output Frame connectors are attached to the right-hand side of the surrounding 
box outline and represent an output channel from the frame's contents. In every 
other way, they are treated the same as Input Frame connectors. 


Constants 

Constant connectors allow a line of text to be SENT to another point in the 
network. You will immediately be prompted for the value that you wish to 
SEND. Enter this string exactly as it would appear in the normal PS 300 
command syntax. Note that syntax checking is not currently performed by the 
Network Editor. You must then route an arc from the constant connector to the 
intended input. 


Variable 

Variable connectors create variables to hold values apart from primitives. The 
variable will be instanced using the optional prefix in the name if \M\ or \F\ are 
included in the name. Any connections going to these variables will be added 
when code is generated. 


In-External 

In-External connectors are a means of making connections to external networks 
or display structures freely. They are input points from outside sources of data. 
You should be careful in using them to make sure that when the code is 
downloaded, these connections already exist if they are data outputs. Also when 
prompted for the connection name, you should enter the complete reference 
including the port number (e.g. INNAME< 1 >). 
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Out-External 

Out-External connectors are output points to external destinations. Make sure 
that when the code is downloaded these connections already exist if they are 
data outputs, though this is not as important as it is with in-external 
connectors. Also when prompted for the connection name, you should enter the 
complete reference including the port number (e.g. <append>Out\/ecList). 



Arc 

An arc is a line indicating a pathway along which data tokens are expected to 
move during execution. They are much like wires between the inputs and outputs 
of integrated circuits. They correspond to the CONNECT or SEND statement in 
the PS 300 Command Language. Arcs must start at a data source (frame or 
external input, a constant, a primitive or detail output) and terminate at a data 
target (frame or external output, a variable, or primitive or detail input). An arc 
may follow a circuitous route, making as many turns as necessary. You start the 
arc as needed and then manually route the arc to the desired endpoint. The 
pathway is automatically grid locked and bent to horizontal or vertical lines. If 
the arc is not completed by making another menu selection before completion, it 
is cancelled. 

When Arc is selected, the cursor changes to an Arc Start Arrow: a single arrow 
which points to the left. Once the arc is started, the cursor changes to an Arc 
End Arrow—an arrow pointing to the right. A corner shape will appear at the 
last bend to indicate in what directions a turn can be made. Arcs can only be 
routed in horizontal and vertical segments. The point of bending is indicated by 
a four-way corner shape. Each time a new corner is added, this corner shape 
moves. Once terminated, the arc will flash once and then become a permanent 
part of the diagram, and all corners will be rounded off to more easily distinguish 
the arcs from the other squared off shapes and lines around them. 

Arcs are homed into the starting or ending connector. 

When an arc is placed, the editor checks the types of the output and input 
connectors and beeps and issues a warning if they are incompatible. An arc 
placed between incompatible connector types will be highlighted. These arcs 
will remain in the diagram and must be deleted explicitly. Note that connection 
type checking is only performed on connections between primitives. Connector 
symbols such as Constants and Variables which have editable strings are not 
checked currently. 
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Duplicate arcs are deleted when a second connection is made between the same 
pair of connectors. There is no need to explicitly delete the old arc. 

Note that Arc can also be selected by pressing Function Key 10 once. 


Labels 

Labels are any text strings in the diagram which can be edited. Labels appear in 
italics to distinguish them from text which cannot be edited. The first shape 
that appears is an arrow which points to the upper right. This is used to pick 
either a point in space at which to place a free-floating label (comment) or to 
pick any object which has a label associated with it such as a function box, or a 
previously defined label. If a new point is picked, then a new comment label will 
be placed there. Otherwise the already existing label will be replaced by the 
new value. 

Once a selection is made, the text-entry hand shape appears and is frozen in 
position where you have pointed. A second, dimmer copy of the hand will move 
about, allowing you to cancel the action by making another menu selection. The 
hand indicates that keyboard entry of text is expected. As you type on the 
keyboard, the text will appear in place at either the position of the previous 
label or at the point at which you are pointing. A second copy of what you are 
editing appears at the prompt line. 

To correct mistakes, the DELETE key on the PS 300 keyboard may be used, and 
deleted characters will be erased. Once the string is complete, press the 
RETURN key and the new value will be stored. You will remain in text-entry 
mode so that more strings can be entered until you enter a return only. In this 
way, you can create text as a block. To change from the Labels selection, pick 
another item from the menu. 


Note that Labels can also be selected be pressing Function Key 10 twice. 
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C) 


MOVE 


All of the diagram objects may be moved once they have been included in the 
diagram, except arcs which are only moved by moving what they are attached 
to. A four-directional arrow will appear to indicate that you may move objects. 
You may pick any of the above objects for moving at any point in their symbol. 
An identical "ghost" copy will then appear to help you accurately place the 
object again. If the ghost-symbol is not placed within the diagram, no movement 
will occur. The four-way arrow will also shrink to indicate that you have 
successfully picked an object up and are in the second half of moving an object. 
Any placement rules that apply to that object, such as placing a connector on the 
frame, still apply during movement. 

To move an object or set of objects to another frame, just pick the detail frame 
that you wish to move into, or pick the outer box outline to move up into the 
parent frame of the current context frame. The frame display will change to the 
selected context and you can repeat this process until you do NOT pick a frame 
or detail. At this point you can place the object or set of objects as if they were 
still in the original frame. Arcs which have had both of their endpoints moved 
are carried along while arcs for which only one endpoint has been affected will 
be stretched if the move is within the same frame, and destroyed if the move has 
jumped into another frame. A detail frame cannot be moved down into itself, 
even though it may originally have been picked up or included in the selected 
area. The frame outline will automatically be restructured to reflect the change 
made due to the move operation. 

MGVE may also be selected by pressing Function Key 8 once. 


MOVE AREA 


By selecting MOVE AREA and indicating any two opposite corners of an area 
box, you can move the items contained within the area. A large lower-left angle 
(first) and a large upper-right angle (second point) set the area. Select the 
lower-left and then the upper-right corners and then move the box to a third 
point. Objects within will be shifted to the new location of the area box. 

Detail frames must be completely contained within the area box if they are to be 
moved. Connectors and primitives need only have their placement point (the 
center of the cursor shape you notice when moving the item) within the area. 
Arcs are moved if their connection points are moved; they will be bent if only 
one endpoint is moved, but moved completely if both endpoints are moved. 
MOVE AREA will not allow you to position items outside of the frame area. 
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MOVE AREA can also be selected by pressing Function Key 8 twice. 
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DELETE 


Any object in the diagram may be deleted. When DELETE is selected, the cursor 
changes to a large X shape which can be used to pick any of the diagram 
objects. The object picked will be removed from the display together with any 
attached arcs. 

Delete can also be selected be pressing Function Key 9 once. 


DELETE AREA 


As with MOVE AREA, you can delete all items in an area by placing any two 
opposite corners of the area box. Objects within will be deleted from the 
diagram with the same inclusion rules as in MOVE AREA. Arcs are deleted if 
either of their connection points are deleted. 

DELETE AREA can also be selected by pressing Function Key 9 twice. 



OPTIONS 


The OPTIONS area of the EDITING menu offers selections that are less often 
used. These are: Change Scale, Redraw Frame, Replace Functions, Update 
Macros, Print Page, and Print Page Set. 


Change Scale 

Change Scale is used to change the overall size of the working page from the 
current size (size 2) up to size 20, which gives 10 times the working space. The 
selected size is noted in the frame data record and is automatically reset when 
you enter the frame. This allows you to have different sized frames within the 
same file. Frame connectors are moved automatically to the outer edge of the 
frame box. 
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Redraw Frame 

This option will clear and redraw the frame if for any reason the display contains 
errors or was partially lost in transmission to the PS 300. 


Replace Function 

This selection lets you pick an existing function in the diagram and replace it 
with another. You are prompted for the name of the replacement function. The 
replacement can be any valid type of function: Initial Function Instance, 
primitive function, macro, or User-Written Function. When functions are 
swapped, existing arcs are checked. They are highlighted if the connector types 
are incompatible with the new function. Arcs leading to inputs no longer 
available in the new function are deleted. 



Update Macros 

This option locates all macros used in the file and compares them to the original 
network file from which they were derived. If the file has since been edited, the 
macro is updated. First, the display is set to the page containing the macro to 
allow you to see the related changes. Then, as with changes to detail frames, 
the existing connections are moved or deleted if the corresponding frame 
connectors in the top level of the source file have been changed. When updating 
is complete, the display returns to the original page. 

Note that updating is based on the internal ID of the original frame connectors. 
If you delete the connector, connections to it are lost even if you rename a new 
connector to the same name. This allows you to change names without losing the 
original connection, but if you delete the original connection, the editor will also 
delete all connections to it in the corresponding usage as a macro. 


Print Page 

This option causes the current page to be printed out on the attached hardcopy 
plotter. When this option is chosen, the display automatically changes to the 
non-menu display (as shown when the VIEWMENU key is pressed) and zooms out 
to full size. After a page is started, you may use the VIEWMENU key or the 
ZOOM and HORIZNTAL and VERTICAL dials to alter the display for hardcopy. 
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Print Page Set 

This option produces a hardcopy of the current frame and all of its subsidiary 
detail frames. If this option is chosen when the top frame is being displayed, the 
entire file will be printed. Form feeds are disabled between pages but a final 
form feed is added at the end of the run. When the run is complete or cancelled, 
the display returns to the original frame. 


NOTES 

1. To cancel a plot request, press Function Key 12. 

2. If the plotter is off-line, the system will hang. If this 
happens, first turn on the plotter. Then press the 
TERM key and the CONTROL/LINE LOCAL to put 
the PS 300 in command mode and enter the 
command: SEND FIX(402) TO < 1 >TOP_ENABLE;. 
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5. FILE CONTROL 


A network file is a structured ASCII file with an extension of .NET which is created and 
edited by NETEDIT. The FILE CONTROL selection offers the following options: 
SELECT NETWORK, BACKUP NETWORK, SCRATCH NETWORK, RECOVER, and 
RENAME NETWORK, 


SELECT NETNORK 



This selection lets you enter the name of an existing file which you want to edit 
or lets you create a new file. You may use directory names or logical names 
preceding the filename. Do not give the file an extension: .NET is assumed by 
the Editor. 


NOTE 

File names are truncated to nine characters. Before a 
new file is created, the directory list in your parameter 
file is searched from beginning to end to see if the file 
name already exists. 


BACKUP NETWORK 


During the course of editing, you can back up the file by selecting BACKUP 
NETWORK which will save the current network file you are working in. Backup 
also happens automatically when EXITing or SELECTing a new network file. 
Backup will not occur if no editing has taken place. Simply pressing the MOVE 
Function Key is sufficient to "touch" a file and consider it edited. 
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SCRATCH NETWORK 


If you wish to abandon the network you are currently working on without saving 
any of it, select SCRATCH NETWORK. As a precaution against stray menu 
picks, you must select this twice before the network is scratched. 


RECOVER 


A log file with an extension of .LOG is kept for every edit of a file. Log files 
are purged after a normal exit from the editor, but only in the current working 
directory. If a crash occurs during editing, the log file can be used to recover 
editing that was done between saves of the file. 

Use the RECOVER selection to rerun the editing operations that were performed 
before the crash. DO NOT LOAD THE ORIGINAL NETWORK. The RECOVER 
selection loads the network automatically. Then, if a log file is found with the 
correct name, it is read in and executed as if the commands were coming from 
the PS 300. The diagram is reconstructed step by step. When the recovery is 
complete, a message is displayed. At this point, select BACKUP NETWORK to 
close the current log file and open another. 

If the crash was caused by the Editor, or if you wish to undo the last few 
commands that you gave, edit the log file and remove the last few lines before 
you select RECOVER. 


RENAME NETWORK 


This selection lets you rename the file you are currently working on. Note that 
the editor does not check to see if the file name you enter already exists. 
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6. CONVERT NETWORK 



This option will automatically produce an ASCII file from the diagram structure 
currently in memory. The file will have an extension of .300 or any other extension 
that is set up in your parameter file NETPARMS.TXT. 

Primitives result in name F:function name; statements. The selection 

optionally adds the prefix in each frame to the primitives within it. Arcs between 
sources and targets produce CONNECT namel<l>: <l>name2; connection statements. 
Constants are sent to targets with SEND value TO <l>name; commands. VARIABLE 
connections cause the creation of the needed variables. External input and output 
connections are connected, expecting the external code to already be resident in the 
PS 300. Free-floating labels in the diagram are added as comn'ients within the code. 


NOTE 

This selection will use the file currently in memory, 
which may be more recent than the accompanying 
diagram file unless you have just loaded or backed up the 
file. 

The following options are available: ASCII Output, Use 
Frame Prefix, Use Macro Prefix, Compile Macro, and 
Suppress Comments. Options are selected by being 
picked once and cancelled by being picked again. When 
an option has been selected, it is highlighted. Some 
options are present by default. 


ASCII OUTPUT 



This selection generates the actual ASCII file from the network diagram. 
Choose this selection after selecting the other options as you wish. If an item is 
highlighted, it is selected; if not, it is disabled. The file generated will have the 
same root name as the source file and an extension of .300 or the user-selected 
extension in the parameter file. 
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USE FRAME PREFIX 


Each context frame has a prefix (upper right-hand corner) which can be changed 
by going one level higher on the detail frame representation or by picking the 
prefix from the header bar. The prefix is (optionally) used before the function 
names to maintain unique naming between frames. This selection lets you 
specify whether or not frame-prefixes are used with function names. If you do 
not select this option, prefixes will NOT be used. 


USE MACRO PREFIX 


This selection controls the inclusion of a special macro prefix in the ASCII code 
file in several ways. The prefix (fV11$, M2$, M3$, etc.) is used to distinguish 
multiple uses of the same macro. If this option is selected when the original 
macro is compiled, then the prefix will always be used later. You should use this 
selection if you intend to make multiple uses of a macro. If the option is off 
when the macro is compiled, then use of the prefix is optional. 

If the option is selected during final code generation, then all macros will include 
the Mn$ prefix. Otherwise, only those macros that were compiled to force 
inclusion of the prefix will use the prefix. 

Prefixes are a way of making multiple copies of a macro with unique names. At 
the same time, by making these optional, the user has the flexibility of 
controlling the function names completely. 



COMPILE MACRO 

A macro must be compiled before it can be included in the code of a network 
that instances it. 

Macros are compiled into an intermediate form of ASCII code which is different 
from the code which the PS 300 normally expects. This form of output is 
selected by the Compile Macro option. When this is selected, the ASCII output is 
written to a macro file with an extension of .MAC which is specially generated 
to allow later inclusion as a macro. Codes are embedded (\n\) which can later be 
interpreted to provide unique prefixes and allow arbitrary nesting of macros. 
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These codes make the ASCII code unreadable to the PS 300. In addition, the 
connections from the top frame connectors are listed at the end of the file to 
allow a network that instances the macro to be hooked up to the right inputs and 
outputs within the file. When one macro is compiled, other macro files are 
merged in with the special codes updated to allow unique prefixing later. 


SUPPRESS COMMENTS 


This selection lets you decide whether or not comments and frame headers are 
included in the code. If you choose this selection, no comments will be 
generated. If you do not choose Suppress Comments, comments and headers will 
be generated in the ASCII file. Comments are included in an arbitrary order, but 
they are placed with the code for that frame. 



o 
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APPENDIX A. INSTALLATION INSTRUCTIONS 


NETEDIT is distributed on magtape along with NETPROBE, the function network debug 
program, and MAKEFONT, the character font editor program. The files supplied on the 
tape are installed in three stages. First, the files are transferred onto the VAX 
system. Then two menu-driven command files, NETBUILD.COM and NETUSER.COM 
are edited to customize the home directory in which the files are to reside. Finally, 
NETBUILD.COM is run to compile and link all of the files. 



TRANSFERRING THE FILES FROM TAPE 


To transfer the files from the distribution tape to the VAX, follow the procedure 
outlined below. 

1. Install the distribution tape on the tape drive. 

2. Enter the following sequence of commands to allocate the tape drive, mount 
the tape, and transfer the files: 

$ ALLOCATE MTA'unit-number*: 

$ MOUNT MTA’unit-number’: EDITOR 
$ COPY MTA’unit-numberL [Destination Directory] 

3. Files take about 10 minutes to transfer. When they have all been copied to 
the system, the '$' prompt re-appears. Enter the following commands to 
dismount the tape and deallocate the tape drive. 

$ DISMOUNT MTAUnit-number’: 

$ DEALLOCATE MTA’unit-number’: 


o 
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CUSTOMIZING THE COMMAND FILES 


A menu-driven command file called NETBUILD.COM is provided to help you 
install the files. Another command file, NETUSER.COM, displays a 
programming utility menu from which NETEDIT, NETPROBE, and MAKEFONT 
are accessed. Both command files must be edited to set up the home directory 
in which the utility program files will reside. With a text editor, enter 
NETBUILD.COM and NETUSER.COM and change the entries which are marked 
with I^INSTALL-DEPENDENT^. These are the name of the directory in which 
the files will reside and the UIC reference. 


INSTALLING THE FILES 


When the changes have been made to NETBUILD.COM, start the command file 
by typing the following command. 

$ @[HomeDir]NETBUILD.COM 

[FlomeDir] is the name of the directory in which the files reside. The following 
menu is displayed. 

Evans &. Sutherland PS 300 Utilities Maintenance 
Command File VI.06 Main Menu 



0) Exit 

1) Initial installation - interactive 

2) Initial installation - submit as batch job 

3) Update Programs individually (menu) 

A) Update Databases/Datafiles Individually (menu) 
5) Utilities (menu) 


To install the network editor files, select 1 or 2 for interactive or batch 
compilation and linking of the entire system. Note that compilation will only 
occur if the object code is missing or if the source code or related files have 
been updated. 

The other selections on the menu display further menus of options for updating 
programs individually, selection 3, updating the data base, selection A, and 
miscellaneous support activities, selection 5. 



FUNCTION NETWORK EDITOR - 37 


FILES THAT ARE LOADED 


The following is a list of all the files that are loaded from the distribution tape. 
The files are ordered by logical groupings and in the same way they would appear 
if you were working in a multiple directory. 


WORK: 

NetParms.TXT 

Init.300 

NetBuild.COM^ 

NetUser.COM^ 

NELinker.COM 

NEPascal.COM 

NEFileLst.DAT 

NEFileDbg.DAT 

NetProbe.PAS 

NetProbe.COM 

NetProbe.300 

NetProbe A.300 

NetEditO.Usr 


A sample parameter file 

ASCII command file to initialize the PS 300 

The NetEdit maintenance command file 

The shared user utility command file 

A command file to link programs with NEUtil library 

A conditional Pascal compilation command file 

The list of files needed for NetEdit distribution 

The list of files needed for NetProbe distribution 

The NetProbe debugger source program file 

The NetProbe maintenance command file 

The NetProbe debugger control network 

Command file to label function keys 

A dummy NetEdit usage log file-copied automatically 


PROG: 

NEComm.MOD 

NEControl.MOD 

NEConvert.MOD 

NEDraw.MOD 

NEEdit.MOD 

NEError.MOD 

NEGraph.MOD 

NEInfo.MOD 

NEMain.MOD 

NEParse.MOD 

NERecord.MOD 

NEUtil.MOD 

NEUtilCon.DCL 

NEUtilTyp.DCL 

NEUtilVar.DCL 

NEUtilExt.DCL 

NEError.DCL 

NetEdit.DCL 

NetEdit.PAS 

NetEdit.EXT 


PS 300 communications 

Intermediate level database management 

Network->ASCII command file conversion 

Object graphics 

High level editing control 

Error handling managementTsee also NEUtil) 

Generic graphics support 

Function and Help database interface 

Top control loop and file control 

Parsing routines 

Low-level database management and I/O 

Shared library of string routines and file handling 

NEUtil Constants 

NEUtil Types 

NEUtil Variables 

NEUtil External declarations 

Error codes 

Global declarations 

Top-level program for NetEdit 

Global external declarations 
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DBASE: 

Config.TXT 

D^* 

Grander.OLD 

GrandCF.TXT 

InitD.PAS 

NetData.PAS 

NetFcn.PAS 

NetLoad.PAS 

NetResolv.PAS 

OldToNew.PAS 

ParsUser.PAS 

PS300Man.DOC 

FNEUser.Man 

DOC: 

Announce.DOC 

Database.DOC 

V106.DOC 

MENU: 

Menu.DOC 

NetMenu.DAT 

NetMenu.PAS 

NETW: 

Editor.300 

Editor.Net 

EdMenuMgr.Net 

EdPlace.Net 

EdSysMgr.Net 

EdText.Net 

FetchPr.Net 

HNet.Net 

PickMgr.Net 

Timer.Net 

^.MAC 

Editor.Doc 

Editor.DSP 

Netlnit.300 

NetEnd.300 


Configuration file function list 

Digit vectors for 1-9 input and output on functions 
P5 function database 
A1 function database 
Merge digits into sets of 1-9 

Generate main function database files (user, system) 
Parse the function appendix file into a database 
Bind output of NetData and NetFcn together 
Merge function and help databases and cross reference 
Compare P5 and A1 databases and produce change list 
Parse the users manual and produce indexed file 
PS 300 User’s Manual appendix on functions 
Function Network editor’s manual 


Announcement of new release 
Function and Flelp Database notes 
V 106 release notes 


Menu construction information 

Menu outline file 

Menu construction program 


ASCII version of network editor support 

Top network file-host communications and integration 

Menu manager network-menu display and highlighting 

PointLine placement network-Drawing 

System management network-Fiardcopy, Memory Alloc 

Text entry network 

Fetch and print network-used in EdSysMgr 
Help page control-dials 
Pick manager 

Clock display timer control 

Macro code versions of net files 

Description of network contents 

Main display structure 

Front end for network editor network 

Tail end for network editor network 
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DRAW: 

NetDraw.PAS Simple drawing program used to draw cursors 

NETran.PAS Translate and scale drawings 

NetDraw.300 NetDraw support network 

NeCursors.300 Combined library of cursor shapes-must be broken into 

individual cursor files for editing. 


ERROR HANDLING 


Should the program crash, the current routine stack will be recorded 
automatically in NETEDIT.ERR. An error message will appear on the status line 
at the bottom of the screen, and the terminal will be reset to the normal 
terminal emulator mode. After a crash, you should save the error file, along 
with the log file that is kept during a session (Eilename.LOG) and your data file 
(Filenam.NET) as they are so that they are available for later examination during 
attempts to identify the problem. 

o 

USER LOG FILE 


NETEDIT.USR is a log file that is kept to indicate who uses NetEdit and when. 
This file nnay become long and should be cleared occasionally by the system 
manager. If you have no use for the log file, it can be disabled in the 
NETUSER.COM command file. 


o 




o 
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APPENDIX B. SAMPLE EDITING SESSION 


In this sample session, NETEDIT is used to design a simple function network whicl;i 
allows the control dials to be used to rotate, translate, and scale displayed objects. The 
transcript illustrates the sequence of operations used in creating the network, and 
shows how to place functions, constants and arcs; create and manipulate detail frames; 
and make connections to external display structures. 
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When NETEDIT is started, it will ask you to select the network to be edited. In 
Figure B-1, the SELECT NETWORK menu item has been selected and the name 
of the network (DIALNET) typed in. The network file will be called 
DIALNET.NET and the file containing the ASCII code will be named 
DIALNET.300, unless specified otherwise in the parameter file. 




Figure B-1. Selecting the Network File 
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In Figure B-2, the menu items for EDITING, ADD ITEM, and FUNCTIONS have 
been selected to get the Functions menu. Here, functions are being placed in the 
top-level frame. All of the functions that have been added here are Initial 
Function Instances, so they have not been assigned user-defined names as 
primitive functions are. The cross-hairs cursor has been turned on to help align 
the function boxes. 
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Figure B-2. Placing Functions With the Cross-Hairs Cursor 
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In Figure B-3, the CONSTANT item has been selected from the EDITING menu 
to allow placement of constants, corresponding to PS 300 SEND commands. The 
user is prompted for the value to be sent as each constant is positioned. Note 
that the constants are not connected automatically to function inputs. Here, 
strings to label the dials according to their functions are being created. 




Figure B-3. Creating Strings to Label the Dials 
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Arcs have been added to connect the constants to the function inputs in Figure 
B-4. Arcs may be inserted either by selecting the Arc menu item or from the 
ARC/TEXT Function Key. 


Evc-'Pis %, Su + herland PS300 FLjnctLon Network Editor V1,06j 



[STATU5: i 
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Figure B-4. Connecting Constants to Inputs With Arcs 


o 
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Detail frames are being created in Figure B-5. Instead of putting on one page all 
the functions to turn input from the dials into transformation matrices, using 
detail frames allows the details to be split up into logically independent blocks. 
Notice that all detail frames initially have no inputs or outputs; the names and 
prefixes are assigned default values automatically. 



IAS0559 


Figure B-5. Creating Detail Frames 
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The prefixes and names of detail frames, along with all other text which is 
displayed in italics, may be edited by selecting the Labels menu item and picking 
the text to be edited. Text can also be edited by pressing the ARC/TEXT 
function key twice. This feature can also be used to add "floating" comments. 
Labels are being added in Figure B-6. 



[5_rAUj^_ _ __ _ __ „ _i 

IAS 0 F 6 O 



Figure B-8. Editing Labels 
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In Figure B-7, the GO DOWN function key has been pressed and the "rotations” 
detail frame has been selected to edit the "inside” of the detail box. This frame 
will have three inputs (from the dials for X, Y, and Z rotations) and three outputs 
(for the corresponding rotation matrices). Input and output frame connectors 
have been placed by selecting the INPUT FRAME and OUTPUT FRAME items 
from the CONNECTOR menu. These items may be placed only on the left and 
right edges of the frame, respectively. 



Figure B-7. Adding Input and Output Frame Connectors to a Detail Frame 
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In Figure B-8, the input and output frame connectors have been assigned 
descriptive names using the LABEL function. Functions are now being placed in 
the detail frame. Since these are intrinsic functions, they are assigned default 
names by the Editor as they are instanced. These may also be edited using the 
LABEL function. 
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Figure B-8. Placing Functions in the Detail Frame 
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Figure B-10 shows that when the GO UP function key is selected, the next 
higher-level frame in the context tree is displayed again. Notice that the box 
for the "rotations" detail frame has grown and that the input and output 
connectors that were placed inside now appear. The connectors appear in the 
same order at both levels; the size of the detail frame box on the higher level is 
adjusted automatically, depending on the number of connectors. 


Evans 8, Sutherland PS3Q0 f-unctLon Network Editor VI. 06! 



Figure B-10. The Next Highest Frame in the Hierarchy 
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Because the sizes of the detail frame boxes change as they are edited, it is often 
necessary to adjust the layout of the diagram after they have been completed. 
In Figure B-i3, the MOVE feature is being used to reposition a function box. 
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Figure B-13. Using MOVE to Reposition Items in the Diagram 
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Figure B-14 shows the top level frame of the completed diagram. Arcs have 
been inserted to route the output from the dials to the appropriate places. 
Connectors to external display structures were added. The floating comment, 
added using the Labels feature, describes how to set up these display structures. 
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External display structures: 

' trans ' TRANSLATE BY 0.0,0 APPLIED TO xrot; 
xrot / ROTATE IN X 0,0 APPLIED TO yrot; 

--q yrot ROTATE IN Y 0.0 APPLIED TO zrot; 

zrot : -- ROTATE IN Z 0. 0 APPLIED TO scale; 

- scale ' SCALE BY 1.0 APPLIED TO user_data; 
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Figure B-14. The Top-Level Frame of the Complete Diagram 
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Here is a listing of the ASCII code produced by selecting the CONVERT 
NETWORK menu item. 

To generate the file, the following options were selected. 

Use Frame Prefix (off) 

Suppress Comments (off) 

Use Macro Prefix (off) 


{ Code generated by Network Editor 6 } 

{ DIALNET} 

{ Frame-Prefix Macro-Prefix } 

{ Frame2:rotations } 
rotationsP8:=F:DXROT ATE; 
rotationsP9;=F;DYROT ATE; 
rotationsP 10:=F:DZROT ATE; 

SEND 100.0 TO < 3>rotatlonsP10; 

SEND 0.0 TO <2>rotationsP10; 

SEND 100.0 TO <3>rotationsP9; 

SEND 0.0 TO <2>rotationsP9; 

SEND 100.0 TO <3>rotationsP8; 

SEND 0.0 TO <2>rotationsP8; 

{ Frame3;2oom } 
zoomPl 1:=F:DSCALE; 

SEND 0.0 TO <5>zoomPl 1; 

SEND 1000.0 TO <4>zoomPll; 

SEND 1.0 TO <3>zoomPl 1; 

SEND 1.0 TO <2>zoomPl 1; 

{ Frame4:pan } 
panP12:=F:XVEOTOR; 
panP13:=F:YVECTOR; 
panP14:=F:ACCUMULATE; 

CONN panP12< 1 >;< 1 >panP14; 

CONN panPl 3< 1 >:< 1 >panP14; 

SEND -1000.0 TO <6>panP14; 

SEND 1000.0 TO <5>panP14; 

SEND 1.0 TO <4>panP14; 

SEND 0.001 TO <3>panP14; 

SEND v3d(0,0,0) TO <2>panP14; 

{ Frame 1:F 1_ } 

{External display structures:} 

{trans := TRANSLATE BY 0,0,0 APPLIED TO xrot;} 
{xrot := ROTATE IN X 0.0 APPLIED TO yrot;} 

(yrot := ROTATE IN Y 0.0 APPLIED TO zrot;} 

(zrot := ROTATE IN Z 0.0 APPLIED TO scale;} 
(scale := SCALE BY 1.0 APPLIED TO user data;} 
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CONN DIALS< 1 >:< 1 >rotationsP8; 
CONN DIALS<2>;< 1 >rotationsP9; 
CONN DIALS< 3>:< 1 >rotationsP10; 
CONN DIALS<4>:< l>zoomPl 1; 

CONN DIALS<5>:< l>panP12; 

CONN DIALS<6>:< l>panP13; 

CONN rotationsP8< 1 >:< 1 >xrot; 

CONN rotationsP9< 1 >:< 1 >yrot; 

CONN rotationsP10< 1 >:< I >2rot; 
CONN zoomP 11 < 1 >:< i >scale; 

CONN panP 14< 1 >:< I >trans; 

SEND 'VERTICAL' TO <i>DLABEL6; 
SEND 'HORIZNTL' TO <1>DLABEL5; 
SEND ' SCALE ' TO < i >DLABELA; 
SEND 'ZROTATE ' TO <1>DLABEL3; 
SEND 'YROTATE ' TO < 1>DLABEL2; 
SEND 'XROTATE ' TO <1>DLABEL1; 



o 
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LIMITED SUPPORT DISCLAIMER 

This software package is distributed by Evans & Sutherland 
as a convenience to customers and as an aid to 
understanding the capabilities of the PS 300 graphics 
systems. Evans & Sutherland Customer Engineering 
supports the package to the extent of answering questions 
concerning installation and operation of the programs, as 
well as receiving reports on any bugs encountered while the 
programs are running. However, Evans Sc Sutherland makes 
no commitment to correct any errors which may be found. 
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PREFACE 



The purpose of this Guide is to introduce both experienced and novice PS 300 users to 
NETPROBE, a network debugger designed to display the activity in a function network. 

The Introduction gives basic background about NETPROBE, including a brief overview 
of how it works and how it can be used. Chapter One describes how to use NETPROBE. 
Chapter Two gives additional information about input and output files and the 
debugging network. 

Appendix A gives instructions for installing NETPROBE. 

Appendix B describes how to customize NETPROBE for your purposes. 

Appendix 0 explains how to port to other machines. 
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1. INTRODUCTION TO THE FUNCTION NETWORK DEBUGGER 


One of the most critical aspects of the PS 300 graphics programmers’ job is isolating 
and correcting problems in function networks. NETPROBE, developed at Evans &. 
Sutherland, can be used as a function network debugger or as a guide in writing your 
own network debugging program, allowing you to see the data values the network 
generates as it runs. NETPROBE is written in DEC Version 2 Pascal for use on a 
VAX/VMS 3.3 and higher system. 

The NETPROBE host program works in two stages: it first reads an ASCII function 
network file and produces a list of the actively used outputs: it uses this list to create 
the debugging network and display structure for up to 300 outputs. It can then be 
downloaded on top of the network to be debugged, and data from the function outputs 
are displayed. The user can optionally edit the list of outputs to reorder or modify the 
display, or generate a list to focus on particular segnients of a function network. 

Each function output used in the network is displayed on a separate display line in a 
15-item page, showing the name of the function and number of the output, the value 
last output, and optionally, a count of how many times the output has fired. Function 
keys provide control over which of twenty pages are displayed, clear the currently 
displayed values, and disable the display. 

NETPROBE is invoked through a VMS command file (NETU5ER.COM) which allows the 
user to initialize the PS 300, download the ASCII command files, run the network 
debugger, and run the Function Network Editor (if installed). 
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2. GETTING STARTED 


Installation instructions for NETPROBE are contained in Appendix A. When all of the. 
files have been installed, run NETPROBE using the NETUSER command file. 

Enter: 


$(3[HomeDir]NETUSER 


where HomeDir is substituted by the name of the directory in which NETPROBE is 
installed. This command file brings up the initial menu of the PS 300 utility programs. 

D 

Evans & Sutherland PS 300 Utilities \/1.06 
Initial Menu 


0) Exit 

1) Initialize the PS 300 

2) Send a file to the PS 300 

3) Run NetProbe - Function Network Debugger (Menu) 

4) Run NetEdit - Function Network Editor (Menu) 

5) Character Font Utilities (Menu) 


Use Option 2 or an equivalent procedure of your own to first download your ASCII 
function network file to the PS 300. This must be done before the debugging network can 
be sent to the PS 300. Then select Option 3. You will be presented with the following 
Debug Menu: 


Evans &. Sutherland Function Network Utility Command File VI.06 
NETPROBE: Function Network Debugger 



0. Exit 

1. Prepare a debug module - complete and sorted 

2. Prepare a debug module in stages 

3. Send a debug module to the PS300 

4. Label the control function keys. 
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Option 1 creates a list of output names and uses the list to create a debugging network, 
performing both operations in a single pass and producing a sorted debug display for all 
the outputs in the network. This is useful for small files. The command file prompts 
you for a file name, runs NETPROBE and outputs a list, and then uses the VAX Sort 
utility to sort the list. It immediately runs NETPROBE again and prepares the debugger 
network and display structure. The default extension for input file names is .300, and 
the extension for the output name list is .PRB. 

Option 2 allows you to directly run NETPROBE to generate an output list or to use a 
list to create a debugging network. You are presented with the following menu: 


NETPROBE: Please provide a source file in one of two formats 

Original PS 300 ASCII Network commands (any extension) 

Assumes CONNECTS are contained on single lines and are the first non 
blank words on the line 

OR 

Output name list: (no extension or .PRB) 

a list of output names and comments (** '* or ’*{”) 

OR 

1. Turn Counting Option ON (OFF) 

Enter filename. Option, or RETURN to exit: 


If any extension other than .PRB (the output list extension) is used, it is assumed the 
filename you provide is an ASCII network file and an output list is created. If no 
extension or .PRB is used, it is assumed you are providing an output list and a debugging 
network is created from it. 

If you enter "1", the count option is toggled so the debugging network counts the 
number of times the output is fired and displays the current count. A counted 
debugging network is slow and should be used only for small numbers of outputs. 

After using NETPROBE to generate an output list, you can also edit the list to reduce 
the number of outputs, improve the quality of printing, or add some outputs. To do this, 
exit the NetUser command file and using the text editor, edit the .PRB file you have 
just produced. Re-enter NetUser and the Debug Menu and select Option 2 to create a 
debugging network using the modified output list. 
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Option 3 sends both the debugger control network ano cne debugging network just 
produced to the PS 300. During the download of the depuq structure, status messages 
appear on the bottom line of the display, including an eno message. The debug control 
network includes the standard support network for any of the oeougging structures, and 
includes the top-level display structure and implementation of the function key 
controls. You must then press SHIFT/LINE LOCAL to enable tne runction keys properly. 

Once the network and the debugging network are downloadec to the PS 300, the 
function keys can be used to control the debug display as Tohov.;;. 


Shift-FKey 9: 
Shift-FKey 10 
Shift-FKey 11 
Shift-FKey 12 


PAGE - 
PAGE + 
CLEAR 
SHOW Y/N 


Display previous debug page 
Display next oepug page 
Clear the current values and counts 
Enable or disable tne debug display 




You must press SHIFT and then the associated key. If you are not actively using these 
function keys for your own function network, you can download labels for the function 
keys by selecting Option 4. 

Figure 1 shows data and values displayed when NETPROBE is run on a function network 
in which dails are used to rotate a cube. 


o 
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NETPROBE: [P53COED. REL.V106. TEST ] EX AMPLE2B ( Pages: 2 } 


PAGE 1 
DIALS< \ > 

DIALS < 2 > 

0 I A L 5 < 3 > 
DIALS<4> 

DIALS<5> 

D I A L S < 6 > 

DIALS<7> 

DIALS<8> 
DoRo-tX2 < \ > 
DoRot X <I > 
DoRot Y 2 <■ 1 > 
OoRotY <1 > 
DoRot22<1> 

D oR o t 2 < 1 > 
DoScal e2< 1 > 


- 1 . S6250E -2 
2.92969E-3 

- 9. 76563E-4 
2.92969E-3 

1.953I3E-3 
2.92969E -3 

- 1 .95313E -3 
1 . 95313E -3 

l.OOQOOOOOE + 0.0. OOOOOOOOE + 0.0.OOOOOOOOE^O 0.OOOCO0OOE + 0,- 9.96764005E - 1 ,7. 9 6777103l-2 
1 , OOOOOOOOE + 0,0.OOOOOOOOE + 0.0.OOOOOOOOE + 0 O.OCOOOOOOEh0.9.6035 8203E-1,2.78 4 98 724E-1 C 
-9. 2729701 IE-1,0, OOOOOOOOE-0, - 3. 74137804E-1 0. OOOOOOOOE + 0, 1 . OOOOOOOOE-0,O.OOOOOOOOE + C 
9.86739725E-1,O.OOOOOOOOE+0,-1.61875105E-1 O.OOOOOOOOE+0,1.000QOOOOE+0,OOOOOOOOOE+0 
-9.98419196E-l,5.51918988E-2,0.OOOOOOOOE+0 -5.51918988E-2.-9.98419196E-1,O.OOOOOOOOE- 
9.98419196E-1.5.5191998SE-2,O.OQOOOOOOE+0 -S.51918988E-2,9.98419196E-1,O.OOOOOOOOE+0 
5.86914063E-1.0.0000 0 000E + 0,0.OOOOOOOOE+0 0.0000000OE+0,5, 869M063E-1 ,0,OOOOOOOOE^O G 




NETPROBE Display ready - Please SHIFT LINE-LOCAL to enable function keys 


c. ccc 
. cooc 

3.74 
1 . 6 1 E 
0 3. C 
0 . 0 Q C 
. OOGC 


Figuce 1. A NETPROBE Example 
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3. ADDITIONAL FEATURES 


ASCII NETWORK FILE - ORIGINAL INPUT 


NETPROBE reads in PS 300 command files and generates a list of the function 
outputs that appear in CONNECT statements. For example: 

CONNECT a<l>:<2>b; 

produces 

in the output list. 

The CONNECT commands must be coded on single lines with no comments or 
other commands preceding the CONNECT command on the same line. For lines 
in which the CONNECT command follows a comment or another command on the 
same line, the outputs are not listed. For example, in: 

{Comment} CONNECT a<l>:<l>b; 

the output a<l> is not listed. 

In: 


CONNECT a<l>b; CONNECT b<l>:<l>c; 
the output b<l> is not listed. 

Commands that have been commented out are ignored. 

Some versions of Pascal may not tolerate a null line at the end of a file and may 
produce an error in reading the file. In this case, the last line shodc ccn^cin at 
least a scace. 


o 
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ACTIVE OUTPUT NAME FILE 


You can either run NETPROBE in one pass (Debug Menu, Option 1), or in stages 
(Option 2) which allows you to edit the output name file (.PRB). You might want 
to edit the output name file to improve the way the debug display appears, to 
increase the efficiency of the debugging network, and to reduce delays caused by 
very active networks and frequently sampled peripherals. 

The output name file may contain blank lines to separate sets of display items or 
it may contain comments. Any line beginning with a space or left curly brace ({) 
is treated as a comment and empty lines (0 characters) are ignored. 

Sorting facilitates lookup. The NETPROBE program discards duplicate output 
names whether the list is sorted or not. 

The debug structure may result in a large and slow network bogged down by 
frequently sampled peripherals (tablet and dial). To reduce the traffic during 
debugging, either edit the output name file and remove some of the outputs 
being monitored, or cut the sampling rate of the tablet and dials. 

NETPROBE generates extensive code for each output. With moderate to large 
networks (over 100 outputs) in which a lot of activity is expected, split the 
output name intermediate file into sections and create debugging networks for 
each of these separately for debug sessions focused on different network 
segments. 

The output name file can be used to check for spelling errors by listing its 
contents. 



DEBUGGING NETWORK 


The debugging network and display file are downloaded on top of your network 
and compete with it for memory, display capacity, function execution, and 
object names. 

Memory can be reduced and function execution enhanced by shortening the 
output name file to focus on limited sections of the network. All 
NETPROBE-generated named entities (function and display structures) use a D$ 
prefix to help reduce naming conflicts, e.g., D$pr_l. Please do not use this 
prefix in your own files. 

Once a debugging network has been passed to the PS 300, to eliminate it do an 
INIT command (refer NetUser, Option T) and retransmit the function network. 
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A?PeND,X A. 


INST, 


( I r I ri Ki 

u l_ M i 1 o i» 


METPF'iGSE is distribuccc; cn .'r,ag';?pe to F&S customers* The msgtape contains severaj 
flies used by NETPFtOBL, as weii as tiie runction Network Editor and Character Font 
F.ditcr flies. The files needed to NETPRGDE are installed in tv>/o stages. First, the 
files are transferred onto tr>e \'AX system ^rem the magnetic tape on which they are 
distributed. Then a menu driver; cemm,end file is run to compile and link all of the files. 


TRANSFERRING THE FiLcS FRUIV! TArt 

O 

To transfer the ’'iies from the dlstrioucion tape ro the VAX, follow the procedure 
outlined below, 

i. Install the distrioution tape on the tape drive. 

2« Enter the foilowino sequence of commands to allocate the tape drive, mount 
the tape, and transfer the files: 

S ALLOCATE MTAOnit-numberL 

$ MOUNT MTA’unit-numberL EDITOR 

$ COPY MTA/unit-number’: [Destination Directory] 

3. Files take up to 10 minutes to transfer. When they have all been copied to 
the system, the '$* prompt appears. Enter the following commands to 
dismount the tape and deallocate the tape drive. 

$ DISMOUNT MTA’unit-numberL 
$ DEALLOCATE MTA'unit-number': 


o 
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CUSTOMIZING THE COMMAND FILES 


To modify the two command files NETPROBE.COM and NETUSER.COM: 

1. Using a text editor, search for and change the entries which are marked 
!*INSTALL-DEPENDENT^. These identify the home directory in which the 
NETPROBE files are installed. 

2. In the NETUSER.COM file, if you don't intend to install the NetEdit file, 
comment out Option A in Top Menu. 

3. Exit from the text editor. 


COMPILING AND LINKING 


NETPROBE is automatically compiled and linked when NETBUILD.COM is run to 
install the Network Editor. (Refer to Appendix A of Function Network Editor 
User's Guide for instructions on running NETBUILD.COM.) NETPROBE is 
compiled and linked on its own as follows: 

1. Enter: 

$(3[HomeDir]NETPROBE 

where HomeDir is substituted by the name of the directory in which 
NETPROBE is installed. 



2. The Main Menu is presented: 

Evans & Sutherland Function Network Debugger 
Maintenance Command File \/106 
Main Menu 

0. Exit 

1. Compile Debugger (NonDebug) 

2. Compile Debugger (Debug) 

3. Copy Debugger to Tape 

Enter selection (0-3) 

Select Option 1 to compile and link NETPROBE and its utility library. 
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Option 2 prepares a debugging version of NETPROBE if you want to debug 
modifications to NETPROBE. Option 3 copies the necessary files (listed in 
NEFileDbg.DAT) to tape for further distribution. 


FILES THAT ARE LOADED 


The following is a list of ail the NETPROBE files that are loaded from the 
distribution tape (other files may be loaded that are used for NETEDIT). The 
files are ordered by logical groupings and in the same way they would appear if 
you were working in a multiple directory. 


Init.300 

NetUser.Com + 

NELinker.Com 

NEPascal.Com 

NEFileDbg.Dat 

NetProbe.Pas 

NetProbe.Com + 

NetProbe.300 

NetProbeA.300 

NEUtil.Mod 

NEUtil'^.Dcl 


An initialization file for the PS 300, used by NetUser 
The user command file 

A command file to link NETPROBE after compilation 
A conditional Pascal compilation command Hie 
The list of files needed in NETPROBE distribution 
The NETPROBE source program file 
The maintenance command file 
The debugger control network 
Oommand file to label function keys 
A library of support routines needed by NETPROBE 
Shared declarations between NEUtil and NETPROBE 


NOTE 

The +’d files must be edited upon installation. NEUtil.^ 
is shared in common with the Network Editor. 
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APPENDIX B. CUSTOMIZATION 


The NETUSER.COM command file is set up to assume a default extension of *.300*. This 
can be modified without side effects to meet user conventions. 


CAUTION 

In editing the NETPROBE.300 debug control network file, 
check to see if any portion of the PS 300 commands you 
intend to alter are referenced in NETPROBE.PAS. The 
commands are described in the NETPROBE.300 file header. 
(Refer to Appendix A for a summary of the files included in 
the distribution tape.) 


The following are changes that can easily be made to NETPROBE.PAS: 

■ Items per page: change the PageSize constant. 

■ Maximum items: change the MaxProbes constant and also modify the display 
structure in NETPROBE.300 to include more pages. NOTE: If there are more than 
512 lines, add more D$clear_all_N functions which can handle 128 outputs each. 

■ Placement of display structure: change the display structure in NETPROBE.300 and 
reset the VSpace constant if you are changing the scale of the display. 
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APPENDIX C. PORTING TO OTHER MACHINES 



NETPROBE is written in Pascal and has been made as machine independent as possible. 

It is limited to standard Pascal with the following exceptions of DEG Pascal, Version 2: 

■ Attributes: Attributes are ANSI extentions to Pascal which qualify how routines and 
constants are used and shared and include [EXTERNAL], [GLOBAL], 
[ASYNGHRONOUS], [ENVIRONMENT], and [INHERIT]. These must be edited out if 
the destination Pascal cannot handle them. 

■ Condition handlers: File errors are trapped by a condition handler called OpenError, 
which helps to recognize nonexistent or protected files and allows the user to try 
again. This can either be reimplemented if possible, or commented out if you are 
unable to provide a condition handler and can tolerate a crash on such a condition. 
Ignore EHandler, another condition handler; it is used only in the Network Editor, 
NETEDIT. 

■ NETPROBE consists of the debugger source program, NETPROBE.PAS, and 
NEUTIL.MOD, a library of support functions that it shares with NETEDIT. If you do 
not have NETEDIT, you do not have to worry about how modifications to NEUTIL 
will affect it. If you do have NETEDIT, you should rename it if you are going to 
make extensive changes to NEUTIL. 

Some of the routines in NEUTIL are not needed and can be commented out when 
converting to another version of Pascal or another language. If you are unable to 
support modules, these two files can be merged together and the associated *.DCL 
files can be merged into the declaration section to provide a single support file. If 
you do merge files, then also modify NETPROBE.COM to directly compile and link 
as a single file rather than compiling and linking in the library. 


o 
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LIMITED SUPPORT DISCLAIMER 

This software package is distributed by Evans & 
Sutherland as a convenience to customers and as an aid to 
understanding the capabilities of the PS 300 graphics 
systems. Evans & Sutherland Customer Engineering 
supports the package to the extent of answering questions 
concerning installation and operation of the programs, as 
well as receiving reports on any bugs encountered while 
the programs are running. However, Evans & Sutherland 
makes no commitment to correct any errors which may be 
found. 









PREFACE 



This document is the user’s guide for the Character Font Editor, MAKEFONT. The 
Character Font Editor is run on the PS 300 to create or modify character fonts. 

MAKEFONT is intended to be similar to the MPS character generator program, but with 
some additional features added. The program is written in VAX-ll PASCAL, and uses 
the procedural interface to the PS 300 for graphical input and output. 

The files needed to run MAKEFONT are loaded from the same distribution tape as the 
NETEDIT (Function Network Editor) and NETPROBE (Function Network Debugger) 
files. For installation instructions, refer to Appendix A of the NETEDIT User's Manual. 

This manual explains how to run MAKEFONT. It is divided into the following sections. 

Section 1 describes how to run MAKEFONT. 

Section 2 explains the functions that can be selected from the Main Control Menu. 
Section 3 describes how to design individual characters. 

Section 4 explains how the character fonts are stored internally on the PS 300 and how 
the font files are stored externally on the host. 





CHARACTER FONT EDITOR 



CONTENTS 


1. INTRODUCTION 


1 


RUNNING MAKEFONT 


1 


2. MAIN CONTROL MENU 


3 



DISCARD 

DELETE 

COPY 

SWAP 

EDIT 

READ STD 
WRITE STD 
READ ALT 
WRITE ALT 
INIT 12‘7 
INIT“255 
Quit 


4 

4 

4 

5 
5 
5 
5 

5 

6 
6 
6 
6 


3. EDIT MENU 7 

MOVE TO 8 

draw" to 8 

ORIGIN 8 

ERASE 9 

EXIT 9 

RETURN 9 


o 




CHARACTER FONT EDITOR 


_______________________ ^ 

A. FONT STORAGE 11 

EXTERNAL FONT STORAGE FORMAT (Standard fonts) 11 

ILLUSTRATIONS 

Figure 1. The Main Control Menu 3 

Figure 2. The Edit Menu 7 




CHARACTER FONT EDITOR - 1 



1. INTRODUCTION 



MAKEFQNT is a program that allows character fonts for the PS 300 to be designed or 
modified. Files may be read and written in formats for both standard fonts (the default 
font loaded when the PS 300 is booted) and user-defined alternate character fonts (a 
BEGIN FONT,..END FONT sequence). MAKEFONT itself runs on a PS 300 under 
VAX/VMS. 

Either a 128-character or 256-character font may be created. There are features 
allowing merging or modification of existing fonts, as well as for creation of new 
characters. In addition, files can be read and written in the format used for 
user-defined alternate fonts. 

This document provides descriptions of the commands available within MAKEFONT. It 
also provides a detailed description of the standard font file format and instructions for 
downloading standard fonts. 

The files needed to run MAKEFONT are loaded from the same distribution tape as the 
NETEDIT (Function Network Editor) and NETPROBE (Function Network Debugger) 
files. For installation instructions, refer to Appendix A of the NETEDIT User’s Manual. 


RUNNING MAKEFONT 

MAKEFONT is run from the command file NETUSER.COM. To bring up the 
menu from which MAKEFONT is selected, enter the following command. 

@ [HomeDirlNETUSER.COM 

[HomeDir] is the name of the directory in which MAKEFONT resides. The 
following menu is displayed. 
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Evans c5c Sutherland PS 300 Utilities \ll.0G 
Initial Menu 


0) Exit 

1) Initialize the PS 300 

2) Send a file to the PS 300 

3) Run NetProbe - Function Network Debugger (Menu) 

4) Run NetEdit - Function Network Editor (Menu) 

5) Oharacter Font Utilities (Menu) 


Select option 5 to bring up the Oharacter Font Utilities Menu. 

Evans &. Sutherland PS 300 Utilities V1.06 
MakeFont: PS 300 Character Font Utilities Menu 

0) Exit 

1) Run MakeFont character font editor program 

2) Convert standard font file to PS 300 s-record format 


Select option 1 to start the MAKEFONT program. Option 2 prompts for the 
name of a standard font file and produces and s-record file (a file in a format 
which the PS 300 can read). This file can then be downloaded to diskette as the 
default character font. The name of the output file is the same as the input file, 
but the extension is .SR. 

When MAKEFONT is run, it first downloads menus and initializes the font. A 
"Ready” message appears when the host has completed the initialization, but 
because of delays due to such things as buffering, it takes about five minutes for 
the PS 300 to be ready to accept commands. The program is really ready to go 
when it responds to menu picks. 
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2. MAIN CONTROL MENU 


The main control menu for MAKEFONT consists of a character selection grid on the top 
half of the screen, and text strings representing various functions on the bottom half of 
the screen. Although only 128 characters at a time can be displayed on the character 
selection grid, you can edit a font with 256 characters by using Function Key 1 to 
toggle between the display of characters 0-127 and 128-255. (This action is carried out 
locally, so this has no effect on what MAKEFONT is doing on the host.) Figure 1 shows 
the Main Control Menu when MAKEFONT is first entered. 





DISCARD DELETE COPY SWAP EDIT 

READ_STD WRITE_STD READ_ALT WRITE_ALT 

INIT_127 INIT_255 QUIT 

R e a d y _____ 

—— IAS0449 


Figure 1. The Main Control Menu 
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Use the data tablet and stylus to select menu items from the bottom half of the 
screen. Some of the functions available (DISCARD, DELETE, COPY, SWAP, and EDIT) 
require you to select one or more characters from the grid to operate on. For example, 
if you pick the menu item DELETE, you will be prompted to select a character to 
delete. You may then pick any number of characters from the selection menu to be 
deleted. To stop deleting, pick another function from the bottom menu. The remaining 
functions perform a single action; when complete, MAKEFONT will return to the 
"Ready*' state. 


The Main Control Menu functions are described below. 


DISCARD 

This function is useful for combining characters from two or more fonts into a 
single font. When a character font is read in from a file, only those characters 
in the current font which are marked for discard will be overwritten by the 
character definitions being read in. A discarded character has a large *X* drawn 
through it on the character selection menu. When the DISCARD menu item is 
picked, the discard flags for all characters are reset. Selecting a character 
while in DISCARD mode complements its current discard status. 



DELETE 

This function is used to delete character definitions from the current font. Any 
characters which are picked while in DELETE mode are removed from the font. 


COPY 


The COPY function is used to duplicate a character definition at a location 
corresponding to a different ASCII code. After selecting COPY, you will be 
prompted to select the character you wish to copy, and then to select the 
character location to copy it to. When the copy is complete, you will be 
prompted to select another character to copy. 





CHARACTER FONT EDITOR - 5 



SWAP 


This is similar to COPY, except that the stroke definitions for the two 
characters are interchanged. Again, when the swap is complete, the operation 
may be repeated. 


EDIT 

The EDIT function allows you to define or modify the stroke definition of a 
character. After selecting EDIT, select the character to be modified. The 
character edit menu (described in Section 2) will then appear. After picking 
EXIT or RETURN on the edit menu, you will be returned to the main control 
menu; at this point, another character may be selected for editing. 



READ^STD 

This function reads a standard font from a file. Only characters which are 
marked for discard will be overwritten. After selecting the function, you will be 
asked for the name of the file; type in a valid VAX/VMS file specification or a 
logical name. 


WRITE^STD 

Selection of this menu item writes the current font to a file, using the format 
for standard fonts. After selecting the function, you will be asked for the name 
of the file; type in a valid VAX/VMS file specification or a logical name. 



READ.ALT 

This function reads a user-defined alternate font from a file. The file is 
assumed to contain a single BEGIN_FONT...END_FONT command. Only 
characters which are marked for discard will be overwritten. After selecting the 
function, you will be asked for the name of the file; type in a valid VAX/VMS file 
specification or a logical name. 
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WRITE_ALT 

Selection of this menu item writes the current font to a file, using the 
BEGIN_FONT...END_FONT format. After selecting the function, you will be 
asked for the name of the file; type in a valid VAX/VMS file specification or a 
logical name. 


INITJ27 

This function initializes a 128-character font (containing definitions for 
characters corresponding to ASCII 0 to 127). All characters are deleted and 
marked for discard when this function is selected. (This happens automatically 
when MAKEFONT is started.) 


INIT_255 ^ 

This function initializes a 256-character font (containing definitions for 
characters corresponding to ASCII 0 to 255). All characters are deleted and 
marked for discard when this function is selected. 


QUIT 


Selection of this menu item causes MAKEFONT to terminate; control is returned 
to the operating system. 
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3. EDIT MENU 


A separate menu is used to design individual characters in EDIT mode. This menu 
consists of the character design grid on the upper part of the screen, and text strings 
representing various functions on the lower part of the screen. The Edit Menu is shown 
in Figure 2. 




M0VE„T0 DRAW_T0 ORIGIN ERASE EXIT RETURN 


M o V e_ -t o __ 

Editing chara cter 103 _ 

IAS0450 


O 


Figure 2. The Edit Menu 
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The design grid coordinates range from -64 to 64 in both X and Y. (This is because of 
the way the standard text fonts are defined. User-defined fonts are actually defined as 
real numbers between 0 and 1, but MAKEFONT does a conversion internally to integer 
coordinates.) Normally, characters are drawn within a "unit square" that corresponds to 
the upper right quadrant of the design grid. If the strokes defining the character extend 
beyond this area, this may cause overlap between adjacent characters. 

If very large characters are being edited. Control Dial 1 may be used to adjust the scale 
of the grid. 

Notice the blinking box on the design grid. This marks the position of the last "move" 
or "draw" in the character definition. 

If the tablet stylus is pressed within the character design grid, a stroke will be added to 
the character definition. The stroke will be either a "move" or a "draw", depending on 
the current state. 


MOVE.TO 

Selecting this menu item causes the current state to be set to "move". Selecting 
a position in the character design grid will then cause a "move" stroke to be 
added to the character. This is the default state upon entering EDIT mode. 


DRAW.TO 

Selecting this menu item causes the current state to be set to "draw". Selecting 
a position in the character design grid will then cause a "draw" stroke to be 
added to the character. 


ORIGIN 

This selection adds a stroke to the character which causes a move to the origin. 
This is useful since all characters in a standard font should have the last position 
at the origin. If this rule is not observed, the characters will be drawn with 
incorrect spacing (although this can be a feature of the font, not a problem). 
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ERASE 


This function causes the last stroke to be erased from the character definition. 
This function may be selected multiple times to erase several strokes. There is 
no way to erase strokes except from the end of the list. 


EXIT 


Selecting EXIT updates the definition of the character being edited in the font 
and returns the user to the Main Control Menu. 



RETURN 

Selecting RETURN returns the user to the Main Control Menu without saving any 
changes that were made to the character being edited. 


o 
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4. FONT STORAGE 


MAKEFONT stores a font internally as an array of pointers to character definitions. A 
NIL pointer indicates that the associated character has not been defined. 

Character definitions are records with two fields: an integer to keep track of how many 
strokes there are, and an array containing the strokes. Strokes are also records 
containing the absolute X and Y (integer) coordinates and a Boolean indicating whether 
it is a move or draw. The maximum number of strokes per character (the dimension of 
the stroke array) is 64, but as this is a symbolic constant it can be changed if needed. 

The primary advantage in using this format for internal storage of the character 
definitions is the ease with which characters can be changed. For instance, swapping 
two characters involves only swapping the two pointers in the font array. 


EXTERNAL FONT STORAGE FORMAT (Standard Fonts) 

The font files are stored on the host as ASCII text. Each record of a font file 
consists of a 7-digit octal number. These numbers are decoded in various ways. 

The first record in the file is an integer, giving the size of the ’’stroke table”, in 
16-bit words. 

The second record in the file is an integer describing how many characters are in 
the font : either 128 or 256. (This number will be referred to as ’n’). 

The remaining records in the file comprise the ’’stroke table”. The first ’n’ of 
these records are integers which give the offset of the corresponding character 
definition in the stroke table. A zero value indicates that a character has not 
been defined. 

Then there are a some zero records in the file, generally five. After these come 
the actual character definitions. 






12 - CHARACTER FONT EDITOR 



Suppose that, for example, the value in location 68 of the stroke table were 599. 
That would mean that the definition for character 67 (68-1) begins at location 
599 in the stroke table. Then the value at location 599 would be the number of 
strokes (moves/draws) defining the character. If location 599 had a value of 10, 
then locations 600 to 609 would contain the move/draw instructions for the 
character. 

The move/draw instructions are stored with the X and Y displacements at 
RELATIVE distances between -63 and 63. The information is packed into a 
16-bit word as follows: 


Bit 0 
Bits 1-7 
Bit 8 
Bits 9-15 


move/draw information (0=move, l=draw) 

Y-displacement 

unused 

X-displacement 


Each character definition has to end with a zero word. Also, character 
definitions have to be aligned on longword boundaries. This means that words 1 
to *n* in the stroke table must all have QDD values, so that the first stroke 
definition command of each character has an EVEN offset. More zero words are 
added here and there in the stroke table to fill it out. 
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LIMITED SUPPORT DISCLAIMER 


The User-Written Functions facility is distributed by Evans & Sutherland as a convenience to 
customers and as an aid to understanding the capabilities of the PS 300 graphics systems. Evans 
& Sutherland Customer Engineering supports the User-Written Functions facility and files 
necessary to use this facility to the following extent: E&S may supply one or two software packages 
that are necessary to support user-written functions. The support of these packages is described 
below. 

1. E&S provides two library files USERSTRUC.PAS and USERLINK.ASM and command 
files to compile, assemble, and link user-written functions with the functions and 
procedures in the standard PS 300 system. E&S also provides utilities to build a file 
containing S-Records in a form suitable for downloading to the PS 300 and to load the 
user-written function via the RS-232 Async interface. These files, any features provided 
in the PS 300 Graphics Firmware that support user-written functions, and the 
documentation are all fully supported. 

2. E&S may also supply the executable code for the cross-software (compiler, assembler, 
and linker) that is used to produce the S-records that will be transported to the PS 300. 

If licensed and purchased through E&S, the executable files will be distributed on a 
separate tape. If the customer buys a license from E&S, no support will be provided by 
Motorola. Any problems with the compiler, linker, or assembler may be reported to 
E&S, but we make no guarantee that they will be fixed. We will answer questions about 
installing and using these programs, but may refer you to the Motorola documentation for 
details about the compiler, assembler, and linker. E&S will only deal with questions 
related to using these programs to write user-written functions. We will not deal with 
questions relating to how to use the cross-software compiler, assembler, and linker for 
any other purpose. 










PREFACE 


This manual is intended for use by experienced programmers both as a guide to writing functions 
for the PS 300 Graphics System and as a reference for doing direct Physical I/O across the 
high-speed parallel interface. 

Modules 1,2, and 3 provide an overview of PS 300 hardware and firmware, details of 
mass memory structures, and how the PS 300 creates and manipulates data and function 
structures. It contains useful information regardless of the programming environment. 

Module 4 discusses general physical I/O procedures and command formats; however, 
specific interface and operating system information must be found in the appropriate 
Customer Installation and User Manual. A list of these manuals is contained on the 
Related Documents page following this preface. 


Modules 5 through 8 and Appendices A through I provide information specific to 
programmers using the Motorola cross-software to write their own functions. 


Appendix J contains operation and data node formats for either programming situation. 


Appendix K lists PS 300 errors and meanings. 
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MODULE 1 


The PS 300 Graphics System 


This document is intended to provide information about the data formats and system function of 
the PS 300. It contains the information necessary to effectively write advanced user-written 
functions and to perform physical I/O functions across the high-speed parallel interface. The PS 
300 is a data-driven, interactive display system. It consists of several general- and 
special-purpose processors and subsystems that are interfaced by means of a general data bus in 
conjunction with a mass memory system. 


1.1 Hardware Components 

The Graphics Control Processor (GCP) is a general-purpose microprocessor that manages 
the data structures in mass memory and initiates the display defined by these data 
structures. The GCP contains 256K (512K in a JCP system) bytes of local program 
memory. The Mass Memory is a general-purpose, dual-ported memory that is 
byte-addressable by the GCP. It consists of one or more Mass Memory cards, each of 
which contains 1024K bytes of memory. (Up to 2048K of mass memory is available on 
the JCP card). This memory may be used as program memory for the GCP, but generally 
provides the memory in which data structures are stored and manipulated by the GCP 
and accessed for display by the Display Processor. The Display Processor accesses the 
data structures in the Mass Memory. Each refresh cycle, the Display Processor traverses 
the data structures and transforms the data to be displayed; performs clipping, 
perspective projections and viewport mapping; and finally draws the data on the CRT. 
The Display Processor is comprised of an Arithmetic Control Processor (ACP), a Pipeline 
Subsystem(PLS) and a Line Generator Subsystem(LGS). (There is also a Refresh Buffer 
between the PLS and LGS on the PS 350 systems). 

• The Arithmetic Control Processor is a special-purpose, bit-slice microprocessor that 
interfaces with the Mass Memory by means of a high-bandwidth, 32-bit memory 
access port. The ACP traverses linked data structures in Mass Memory, referred to 
as SOD (Set-Operate-Data) structures. The SOD structures contain commands that 
indicate the functions the ACP is to perform for each SOD data block. These include 
commands to modify the state of the ACP and process three-dimensional data. 
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The state of the ACP is considered to be those values which are context dependent, 
such as transformation matrix contents, viewport boundaries, color, line texture, etc. 

The SOD structures and the commands which initiate and control the ACP functions 
are detailed in later sections. In traversing the SOD structures, the ACP performs all 
of the matrix operations required to transform data points before passing the 
transformed data coordinates to the Pipeline Subsystem. 

• The Pipeline Subsystem accepts transformed data coordinates from the ACP and 
performs clipping, perspective division, and viewport mapping on the data to be 
displayed. The Pipeline Subsystem processes data asynchronously in relation to the 
processing performed by the ACP. The processed data is then output to the Line 
Generator Subsystem. 

• The Line Generator Subsystem accepts screen coordinate data from the Pipeline 

Subsystem. From this data, the Line Generator Subsystem produces images on the 
CRT. 

1.2 PS 300 Graphics Firmware 

The primary purpose of the PS 300 graphics firmware is the manipulation of data structures that 
are traversed by the Display Processor to display information. To do this, the graphics firmware 
must: 

€ 

1. Perform startup operations 

2. Communicate with the host computer support software 

3. Receive input from graphics peripherals 

4. Initiate updates of the data structures 

5. Perform data storage allocation/deallocation , 

6. Initiate the traversal of the data structures by the Display Processor 
The graphics firmware is made up of: 

PS 300 Startup Code • 

This determines hardware availability and status by performing a series of self-tests on 
hardware components. Following these self-tests, system configuration parameters and ^ 
the 68000 Graphics Control Program are loaded from the PS 300 floppy disk drive. 
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PS 300 Communications and Graphics Code 

Once start-up code is completed, the Graphics Control Program then initializes all data 
structures and communications handlers and awaits input from host software or keyboard. 

Included in this document are several block diagrams of data structures. The values of fields are 
indicated graphically, as in the following examples: 
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MODULE 2 

PS 300 Mass Memory Structures 



PS 300 data structures are built by the GCP and exist in mass memory. Data structures in the 
PS300 which can be named by the user are referred to as Named Entities. Named Entity blocks 
represent function instances, variables, character fonts and display data structures. These types of 
structures are called Named Entities, even if there is no associated name. Hence, the term 
Named Entities refers to blocks which can be (but not necessarily are) named. The name 
associated with a Named Entity is kept in a block referred to as an alpha block. An alpha block is 
a data structure that contains the location in mass memory of a Named Entity as well as the name, 
if any, associated with that Named Entity. Every Named Entity, regardless of whether the user 
has chosen to name it or not, has an alpha block associated with it.Alpha blocks with names are 
listed in a dictionary that is indexed by means of a fixed-length hash table. The hash table is an 
array of pointers to forward and backward linked lists of alpha blocks. Naming a node causes the 
name to be entered into a hash table along with a poijiter to where the current node associated 
with that name resides in PS 300 Mass Memory. 

Though the address of the Named Entity referred to may change often, the address of the alpha 
block remains constant until an INITIALIZE command is entered, which will destroy the alpha 
block. 


In general, all references to a Named Entity structure are indirect, through its alpha block. 
Whenever some node in the system references another node, a pointer is placed to the alpha 
block (known as an “alpha pointer”) so that the currtot node associated with that name can be 
determined. 


2.1 Alpha Block 

* • 

The alpha block structure is shown in Figure 2.1. Some contents of the alpha block are; 

• Datum Pointer • v 

The Datum pointer points to the location in Mass Memory of the Named Entity to which 
the alpha block refers. 


CS 
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• Dictionary Forward and Backward Pointer 

The dictionary forward and backward alpha pointers allow an alpha block to be linked 
into the dictionary list. 


• Usage Count 

Usage count indicates the current fiumber of references made to the alpha block in the 
display data structures or function networks. It is necessary since names may be multiply 
referenced. The usage count must .be incremented for every new pointer to this alpha 
block, and must be decremented each time a pointer to the block is removed. When the 
usage coimt becomes zero, the alpha and its associated Named Entity block are removed 
from storage. Two utility routines, Incausage and Decausage exist to perform these 
actions. 


Note 

It Is Very Important To Keep This Coimt Accurate! If the count is too 
small it will crash the system at some later time, if it is too large the 
memory will never be recovered. 


• Alock 

This is a Boolean value that is set true when the alpha is being manipulated, false 
otherwise. Normally, the utility procedures provided handle locking and unlocking of this 
field when it is necessary. 


• Ci_num 

This field is a positive integer which indicates which instance of the Command Interpreter 
created the alpha block. Each Command Interpreter has associated with it a Ci_num 
which is the parameter that is given when instancing the command interpreter (for 
example, Clinstance := f:ci(4);). This number is kept in the CFs private data and is 
written into the alpha block for each alpha it creates. Note that once an alpha has been 
created, it “belongs’’ to this Cl until an INIT command occurs. Even redefinition of the 
contents of an alpha block by another instance of the Cl does not change ownership of 
the alpha. When the Cl function instance receives an INITIALIZE command, it can then 
identify those alphas in the dictionairy which it created and which need to be destroyed. 


• Gcpdatum 

The Gcpdatum points to the location m Mass Memory of the Named Entity to which the 
alpha will refer after all current data structure updates have been done. Whenever the 
GCP needs to find the Named Entity which is referred to by an alpha, it must look at this 
field rather than the Datum field, since the Gcpdatum field has the latest changes. This 
field disagrees with the Datum field only when an alpha update is pending. See the 
section on Alpha Updates for further information. 
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• Namelength 

The namelength specifies the byte length of the name associated with the alpha block. 

• Name 

The name is a string of characters representing the name of the Named Entity, 




Figure 2-la. Alpha Block 
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TYPE 

Ptxalphablk 

PtrNamedEntity 

Namespell 

Lock 

Intl6 


^ Alphablk; 

" NamedEntity; 
ARRAY[1..255] OF Char; 
Boolean; 

-32768..32767; 


Alphablk = 

RECORD 

Datum: Ptmamedentity; 
Dictfwd: Ptralphablk; 
Dictback: Ptralphablk; 
Usage: Inti6; 
aLock : Lock ; 

Ci_num: Int8 ; 

Gcpdatum: Rmamedentity; 

UserDatum: Ptmamedentity; 
Namelength: Intl6; 

Name: Namespell; 

END; { of Alphablk } 


{ Alpha’s Named Entity } 

{ Dictionary list pointers } 

{ Reference count } 

{ Lock on this alpha } 

{ ID number of creating Cl } 

{ Alpha’s Named Entity } 

{ after all updates } 

{ Reserved for future use } 

{ Number characters of name } 
{ Alpha’s name } 


Figure 2-lb. Pascal Data Definition of Alpha Block 


2.2 Named Entity Block 

A Named Entity is a basic data structure type of the PS 300 system that can be named and 
referenced. Some of the Named Entity types are as follows: 


• Function Instance • 

A function instance is a Named Entity that performs a given function, based upon a given 

set of inputs, and creates a given set of outputs. 

• Display Structures ^ . 

The ACP traverses these each refresh cycle for display purposes. 

• Character Font Block ^ 

A character font block is a structure that defines the strokes or vectors which make up the 
characters. It consists of an integer that indicates this display structure is a character font 
block, a 128 (or 256)-entry character font table (one for each character of the 128 
displayable ASCII character set), and up to 128 (or 256) associated character stroke 
blocks (with strokes in relative mode). 
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2.2.1 Function Instance Block 

Functions perform specific operations by accepting input, processing it, and sending output to 
other functions. Generic functions exist as Pascal-callable procedures which reside in the 
- Graphics Control Program. Since each function is guaranteed to run to completion once execution 
has begun, the module of code for a generic function can be shared among several instances of 
the function without regard to reentrancy requirements (as long as sufficient mass memory is 
available). Care must be taken, however, to ensure that all residual data are kept on a private 
data queue which is accessible only to that function instance. Functions may be used individually 
or be part of a network of functions to perform a required operation. Three types of functions 
exist: standard functions, system functions, arid I/O functions. 

1. Standard functions 

Standard functions include all user-created functions and those functions receiving input 
from devices. Standard functions communicate through their inputs and outputs. They 
have specified priorities and are scheduled for execution accordingly by the Scheduler. 

2. System functions 

The system functions are special-purpose functions which can be created only by the 
firmware itself and which cannot be part of a user-created function network. One system 
function is the DESTROY function, which returns memory blocks to free storage. Its 
^ input queue is accessible to all functions, not by a function connection, but by a global 
variable. Another system function is the UPDATE-FORMATTER function, which takes 
update blocks from a system-wide update list and prepares their contents for the ACP to 
work on. This function has no inputs or outputs but is activated when an update is put on 
the update list. The UPDATE-KILLER function also has no inputs or outputs as other 
functions do. It is activated when update blocks have been processed by the ACP and 
need to be destroyed. 

3. I/O functions 

« 

I/O functions perform input/output operations for I/O devices only. One input function 
and one output function exist per device. I/O functions are unique in that they 
communicate with interrupt-level routines through special buffers rather than through the 
normal function communication method of queued messages. Specifically, an input 
function differs from other functions in that it has no input queues. Instead, its data 

♦ • come from the specific hard-coded buffer associated with its input device. When an input 

interrupt occurs, an interrupt routine places all input in this buffer and determines if an 
input function is waiting on that buffer. If so, the input function is activated. An output 
function is special in that it is the only function which waits on both an input queue and 

• V an output “queue’*. The output function receives input as queued messages and outputs 

to an associated hard-coded buffer through a special interrupt procedure. It may have to 
wait either for room in the output buffer or for new queued messages. Note that because 
I/O functions can communicate with other functions, they have names which the host can 
access (for creating function networks), as well as standard communication queues for 
that purpose. 
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• Function Instance Data Structures 

When the need for a particular function arises, an "instance” of the generic function is 
created by the user or by the system. This function instance has its own unique set of 
input sotirces, output destinations, and private data. 

Before a function instance can be created, enough mass memory must be reserved to 
accommodate the necessary data structures. These data structures are: a Function 
Instance block, a Function Inputs block, and Outset blocks. 

To understand these data structures, it is important to note that PS 300 Pascal is not 
standard Pascal. In standard Pascal, the length of all records is known at compile time. 
In PS 300 Pascal, the size of one array in the record can be determined at runtime. 
Because this array is placed in the last field of the record, the compiler can correctly 
compute the starting offset of that last field (as well as all prior fields). Standard Pascal 
allows a similar subterfuge in permitting variant records. With the PS 300 Pascal, note that 
the variance is extended to include the size of a final array. For example, a variable 
number of inputs and outputs is allowed for a function in«;tance. The last field in the 
function instance block is an array (of variable length) of outset pointers (one for each 
output). In order to allow a variable number of inputs, a separate Function Inputs block 
was defined whose last field is an array of input queue pointers (one for each input). 

The Function Instance structure contains all the references to data needed to define a 
function instance. This information includes (a) an index identifying the Pascal-callable 
procedure that performs the required generic function, (b) the input source (s), (c) the 
output destination(s), (d) a priority value for scheduling purposes, (e) the current status 
of the function, and other information about the function. 

The Function Instance block contains the address of a Function Input block. Each input 
queue is defined by a Message Queue block. The Function Inputs block contains the 
number of inputs for the function, a message queue for the private message of the 
function, and one message queue for each other input of the function. 

The Message Queue block references the input data itself. It also indicates if the function 
instance is waiting for input on its associated data in order to be activated, though this 
technique is used only if the function requests to wait for a specific input rather than a full 
set of inputs. 

The Function Instance block also points to Function Outset blocks. The Function Outset 
block identifies each of the output destinations of this function instance, including the 
appropriate queue of the receiving function or display data structure. 

The Function Outset blocks contain two intS’s (aside: an intS implies that the maximum 
degree of fanout from a function is 127). One intS, Maxn, gives the capacity of the 
block; the other, N, gives the capacity actually used, where capacity means the number of 
output designators that will fit in the block. 
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A negative N is initially indicated. If a function attempts to send data out of an output 
port with a negative N, a warning “No connection ever made out of ...” (or somesuch) is 
issued, and the used field is set to zero (this prevents repeated warnings of no connection 
ever made). An effect of a DISCONN ... :ALL on that output is to set N field to zero; 
this provides a means of the user specifically to indicate that no connection was intended 
to be made out of that input and hence disable the warning. The N also only goes down 
to zero (i.e., is not made negative) if each connection ever made is specifically removed 
(as opposed to the :ALL technique). 


Figure 2-2 illustrates the general relationship between these function instance data 
structures. Then next sections detail each of these structure blocks. 



Figure 2-2. Function Instance Data Structures 


• Function Instance Block 

A function instance is represented in storage by a function instance block of the format 
shown in Figure 2-3. 
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Function Instance 


Named Entity Pointer - 


Fimction Status 


Priority Value 


My Alpha Pointer 


Debug Alpha Pointer 


Debug Alpha Pointer 


MyintS 


Carve Memory 


Debug Function Code 


Pascal Function Code 


I--Function Inputs Pointer 


Num of Outputs 


lamMemOK 


NumNonNull 


Outset 1 Pointer 


Outset n Pointer 


CONST 

Fcninstance 

TYPE 

PtrNamedEntity 

Ptralphablk 

Ptrfcninputs 

Ptroutset 

IntS 

Fcninstance 

RECORD 


= 4; 

= ^ NamedEntity; 

4 t " Alphablk; 

= Fcninputs; 

= ^ Outset 

= -128..127 


Type: Fcninstance; 

Schednext: PtrNamedEntity; 

Status: Fcn_status; 

Priority: IntS; 

Myalpha: Ptralphablk; 

A_dbgcmdex: Ptralphablk; 

A_dbgprint: Ptralphablk; 

MyintS: int8; {1-byte private message} 
Carvememory: Boolean; 

D_fencode: Fentype;* 

P_fencode: Fentype; 

Inputs: Ptrfcninputs; 

Noutputs: IntS; 
lamMemOK : McinOKindex; 

NumNonNull : Inti6; 

Outputs: ARRAY [DtimmysizeJOF Ptroutset; 
END; 





Figure 2-3. Function Instance Block and Pascal Data Definition 
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The fields of the function instance block are detailed below. 

- Function Instance 

This field identifies this block as a function instance block. 

- Named Entity Pointer 

The second field in the function instance block is for use by the Scheduler. The 
Named Entity pointer identifies the function instance next to run on the active or 
priority function list. 

- Function Status 

This field indicates the current state of the function instance. 

- Priority Value 

The priority value gives the priority of the function. The Scheduler uses this value at 
scheduling time to determine when this function will execute in relation to other 
functions ready to run. Lowest priority is 15 and the highest is 0. 

- Alpha Pointer 

The alpha pointer (Myalpha) points to the block in memory containing the user- or 
system-given name of the function instance. Note that because a function instance is 
a Named Entity, it may be named by the user. Through this name, the user may 
create the function instance, delete it, or display data structures. 

- Debug Alpha Pointers 

These alpha pointers are currently not used. 

- MyintS 

This field is used by individual functions for private data. For example, some of the 
data concentrator functions indicate which port this function serves via this field. 

- Carve Memory 

This is a boolean which indicates whether this function might need to carve memory. 

- Debug Fimction Code 

This field identifies the generic function (a Pascal-callable procedure) to be called 
when the function instance is executed. 

- Pascal Function Code 

This code identifies the generic function (a Pascal-callable procedure) to be called 
when the function instance is scheduled for execution. (This field is always the same 
as the Debug Function code.) 
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- Function Inputs Pointer 

The function inputs pointer points to a function input block that lists the function 
instance inputs. 

7 Number of Outputs 

Number of outputs specifies how many different output values are to be sent from this 
function to other functions. 



- lamMemOK 

This is index into array of users. Free storage used by this function will be charged to 
the user according to this index. Also, the scheduler uses this index to determine 
which user category this function is in. 


- NumNonNuU 

This represents the nximber of inputs queues which still need data in order for this 
function to be able to run. When a message is sent to a previously empty input queue, 
this number is decremented; when it becomes 0, the function is ready be executed. 

- Outset Pointers 

Each function output port has an outset block. The outset block identifies output 
destination (s). 

• Function Inputs Block 

A function input arrives in the form of a queued message. A function inputs block, see 
figure, contains the input queue headers. 
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Number Inputs Not Used 

- Private Queue Head Pointer -- 

- Private Queue Tail Pointer - 

Cqueue Ownerwait 

- Input 1 Queue Head Pointer - 

- Input 1 Queue Tail Pointer - 

Input 1 Cqueue Ownerwait 

• 

• 

• 

- Input n Queue Head Pointer - 

- Input n Queue Tail Pointer - 

Input n Cqueue Ownerwait 

Reserved 


TYPE 

Mqueue = 

RECORD 

Qhead: Ptrqdata; 
Qtail: Ptrqdata; 
CQueue : boolean; 
Ownerwait : boolean; 

END; {of Mqueue} 


(head of queue} 

{tail of queue} 

{true - Cqueue, false ~ Tqueue} 
{true function waiting on this} 
{queue for activation} 


Fcninputs 

RECORD 


Nin: Int8; {number of input queues} 

Private: Mqueue; {private data} 

Inputqueues: ARRAY[Dummysize] OF Mqueue; {actual input queues} 
END; {of Fcninputs} 


Figure 2-4. Function Inputs Block and Pascal Data Definition 


The fields of the function input block are detailed below: 


- Number of Inputs 

Number of inputs specifies the number of (public, not private) input queues of the 
function instance. 
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- Private Message Queue Head and Tail Pointers 

A private data queue retains variables needed from one execution of the function 
instance to the next. Private message queue head and tail pointers point to the first 
and last messages on this queue. 

- Inputqueues Head and Tail Pointers 

These pointers point to the first and last messages on this queue. 

- Cness 

This boolean value indicates if this queue is to be treated as a Constant or Trigger 
queue. Each function is initialized with specific defaults for each queue. This value 
may be changed from its default via the SETUP CNESS command. 

- Ownerwait 

This indicates if the function is waiting for input on this queue. It is only used if the 
function requests to wait on this specific queue. Most functions do not make use of 
this field anymore. 

• Outset Block 

An outset block, shown in Figure 2-5, gives the set of destinations for an output of a 
function. Each different output has an outset block. An outset block may specify any 
number of function instance or display data structure recipients; each is identified by its 
alpha pointer. The input number designates which input queue of the destination 
function or structure will receive this function's output. 

• Qdata Blocks 

A function's input queues are queues of Qdata blocks, each containing a message from 
another function. A message can communicate either data or an event (or both), and is 
one of many types. Each Qdata block has a pointer to the next message on the queue, a 
field indicating the message type, followed by the message itself, whose contents and 
format depend upon the message type. Note that some Qdata are special types put on a 
private queue. A private data queue retains variables needed from one execution of a 
function instance to the next. 

• Function Instancing 

The function instance data structures provide the means for interfunction 
communication. Most commonly, function instances receive inputs from and send 
outputs to other function instances within a “function network.'' Function instancing is 
the process of creating a function instance and tying it to the existing function network. 
Some function instances are instanced automatically in the PS 300 initialization code; 
others are done at the user's command. 
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Number Recipients 

Number this block 

- Alpha Pointer 1 - 

- Input Number 1 - 

Ci_num 

Memok 

- Alpha Pointer 2 - 

- Input Number 2 - 

Ci__num 

Memok 


• 

• 

• 

- Alpha Pointer n - 

- Input Number n - 

Ci__num 

Memok 


TYPE 

Ptralphablk = "Alphablk; 

Int8 = -128..127; 

Intl6 = -32768..32767 


Outdesignator = 

RECORD 

Who: Ptralphablk; 
n: intl6; 

Cl^nuin : int8; 
memok : memokindex 
END; {of Outdesignator} 

Outset = 

RECORD 
n: Int8; 

Maxn: Int8; 

o: ARRAY [Dummysize] OF 
END; (of Outset} 


(Alpha of destination} 

(index into that block} 

(Cl that did the connect} 

(user classification of the connection} 


(set of output designators} 

(number of recipients} 

(# of Outdesignators this block can hold} 
Outdesignator; 


Figure 2-5. Outset Block and Pascal Data Definition 


To create a function instance, the system does the following: 

1. Obtains a function instance block for the function and loads it with the function code 
and priority values. 

2. Assigns to the instance the user- or system-specified name (in an alpha block), ties 
the alpha into the name dictionary (if it is not already there), and enters the alpha 
address into the function instance block. 
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3. Sets up the input, output, and private data queue structure. This involves creating a 
function inputs block, and an outset block for each output, then tying the blocks 
together in the proper manner. 

4. Executes initialization code for the function, if any exists. 

5. Marks the function’s state as “Act on update*’ and then asks the ACP to associate the 
function with its name. (Some functions created at boot time are just directly 
associated. This is safe since the ACP cannot be using that name yet since the ACP is 
not running). 

6. When the update killer function in the GCP sees that the name association for a 
function has been performed, it activates the function. The next time the scheduler 
runs, it will place the function on its appropriate active list. 

7. Executes the function. During this first execution, the function causes itself to wait for 
data in the appropriate manner (i.e., from a queue, from the clock, or from a 
device). In addition, it may perform some initialization specific to that function (such 
as setting up its private queue data), although this is usually done in the function 
initialization code described above. 

Once a function instance has been created, the user or system can connect it into the 
existing function network by issuing a command to tie the function’s outputs to their 
destinations. This is done, for any given output, by entering into the outset block a 
pointer to and an index into the receiving function instance or data structure node. In 
the same manner, other functions may be connected to this function through its alpha (or 
name). Note that since connections to receiving functions (and display structures) are 
made via their alphas, those functions (and structures) need not exist prior to this 
connection, and a redefinition of the receiving function does not destroy connections 
from other functions into it. 


2.2.2 Display Structures 

Display structures in the PS 300 represent the operations and data that form the two- or 
three-dimensional objects constructed by the user. The objects that are formed are represented 
by a structured display file that is traversed each refresh cycle by the ACP. The structured display 
file is created and modified under control of the Graphics Control Processor (GCP, the 68000 in 
the system). The elements of the structured display file are quite simplistic in nature, forming an 
acyclic graph of nodes that are either: 

• Control blocks (DCR, DCB) 

• Data (dots, lines, or characters) 

• Operations that change the “state of the machine” for descendent data 

• Set nodes that contain lists of branches of the acyclic graph that are to be traversed. 

With the exception of the control blocks, these nodes are all Named Entities, thus they each have 
an associated alpha block which may include a name. 
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2.2,2.1 Control Blocks 

The Display Control Root (DCR) and Display Control Block (DCB) are control blocks which 
serve as the major communication links between the ACP and the GCP. The DCR contains the 
items used for communication between the GCP and ACP. The DCR contains the address in 
Mass Memory where the first DCB resides. A DCB is the topmost node of the user’s structure; 
one DCB exists for each user. 

• Display Control Root (DCR) 

The Display Control Root (DCR) is a block of storage that serves as the root node of the 
display data structures. The DCR, in conjunction with the Display Control Blocks, is the 
only means by which the GCP and the Display Processor (ACP) communicate directly. 
During system initialization, the GCP writes the address of the DCR to the ACP. The 
ACP microcode can then read this address and store it internally. The ACP controls the 
refresh synchronization by means of the DCR. The ACP polls a flag in the DCR, waiting 
for the flag to be set by the GCP to initiate a refresh cycle. When the GCP sets the flag, 
the ACP begins traversing the display data structures. When the ACP completes 
traversing the data structures, it performs the updates specified by the DCR, resets the 
flag, and restarts the process by polling the DCR again and then waiting for the GCP to 
initiate another refresh cycle. The DCR is shown in Figure 2-6. 


PS 300 Advanced Programming 


2-15 


Mass Memory Structures 



Display Processor Busy Flag 

Do Updates Flag 

Plot Done Flag 

Plot Select 

- Upblock List Head -— 

- 1st DCB Pointer - 

Transmit Trigger 

Progress Flag 

X Start 

Y Start 

//////////////////////////////// 

Transmit Mode 

- FIFO Head - 

- FIFO Tail - 

//////////////////////////////// 

AGP Dispose Flag 

//////////////////////////////// 

- Free Storage Size - 

- Free Storage Pointer - 

Timeout Delta 

AGP Status 

- Upblock List Tail - 

- Timeout Function Pointer - 

- AGP Free Owner - 

ACP Free Lock //////////////// 

- Last Shade Block - 



Figure 2-6a. DCR Block 
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TYPE 

Intl6 

Bitmask 

RrAvupblock 

PtrDCB 

Ptmamedentity 

Lock 


-32768..32767 

=Intl6; 

"Avupblock; 

="DCB; 

^Namedentity; 

BOOLEAN; 


DCRblk 

RECORD 

ACPbusy: Intl6; 

Doupdates: Intl6; 

Plotdone: Bitmask; 

Plotselect: Bitmask; 

Avup: PtrAvupblk; 

FirstDCB: PtrDCB; 

Xmit_Trigger : Inti6; 

Progress_flag : Inti6; 

X_Start : Inti6; 

Y_Start : Inti6; 
unusedO : Inti6; 

Xmit_mode : Intl6; 

FIFO_head : Ptrqdata; 

FIFO_tail : Ptrqdata; 
unusedl : Intl6; 

ACPDisposeFlag : Inti6; 
unused2 : Inti6; 

ACPFreesize : Integer; 

PtrACPFree : PtrIntArray; 

TimeoutDelta : Inti6; 

ACP_Status : Inti6; 

Avupt: Rravupblk; 

Timoutfcn: Ptmamedentity; 

ACPFreeowner : Ptmamedentity; 

ACPFreelock : Lock; 

LastshadeBlock : Ptrqdata; 

END; 

Figure 2-6b. Pascal Data Definition of DCR Block 


As the figure shows, the DCR consists of several items, ten of which are explained below: 

- ACP Busy Flag 

The Display Processor busy flag (ACPbusy) is the location in Mass Memory that the 
ACP polls to determine when to begin traversing the display data stmctures. The GCP 
sets this location to a non-zero value to initiate a new refresh cycle, synchronizing the 
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setting of this location with the line frequency. When the ACP has completed its 
traversal (and update) cycle, it zeroes this location, indicating it is idle again. 

- Do Updates Flag 

The Do Updates flag (Doupdates) is a location that the ACP examines at the end of 
each refresh cycle to determine whether ^dates are to be performed. If this location 
is non-zero, then the update list head must be examined to determine the address of 
the first update to perform. 

- Plot Done Flag 

This field is used when a hard copy (plot) has been requested. Bit 10 in this field is 
set to indicate to the GCP that the plot has been completed. 

- Plot Select Flag 

The GCP sets bit 10 in this field to indicate to the ACP that a hard copy (plot) has 
been requested. Note that bits 8 and 9 indicate which hard-copy device has been 
selected for use. 

- Update List Head and Update List Tail 

When a change needs to be made in the display data structures, the GCP 
communicates the change to the Display Processor in an update block (Avupblk). 
The update block is on an update list, which has a head and tail pointed at by the 
DCR update list head and list tail. The update list head indicates the address of the 
first update the ACP is to perform. Once an update cycle is completed, the ACP 
zeroes the (Doupdates) flag. The update list tail is used only by the GCP. When an 
update cycle is completed, the GCP returns the blocks in the update list to the free 
storage pool. 

- First Display Control Block Pointer 

The first Display Control Block pointer (FirstDCB) is an address in Mass Memory 
where the head of a list of Display Control Blocks resides. 

- Size of Free Storage Block 

This field gives the size in bytes of the contiguous block of free storage which has been 
allocated for the ACP’s exclusive use for operations such as sectioning and hidden line 
removal. A value of zero implies that no storage has been set aside for ACP use. 

- Pointer to Free Storage Block 

This field gives the pointer to the free storage block described above. 

- ACP Status 

This field is used as part of an intricate communications mechanism between the ACP 
and the GCP. When any solid modeling command is invoked via the solid_rendering 
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function, this field is written to by the ACP to indicate either that solid modeling is in 
progress, that solid modeling has completed or that an error has been detected by the 
ACP. On the GCP side, this field is checked by the solid__rendering function to 
determine when the ACP has completed its part of a viewing operation. The ACP 
timeout function must also check this field (along with some other fields) to determine 
if the ACP has had a genuine timeout or not. If the ACP has detected an error while 
performing a viewing operation, an error number is written to this field to indicate the 
type of error. The error will be brought to the attention of the GCP as either the 
solid_rendering function will see the error number in this field, or the timeout function 
will see it (the ACP forces a timeout when an error has been detected.) 

- Timeout Function 

This field, used only by the GCP, is a pointer to a function instance which restarts the 
ACP and preserves any pending updates. The function is activated when the ACP 
requires 120 clock ticks or more to walk the display structures, which is usually when a 
recursive data structure exists. 

• Display Control Block (DCB) 

The Display Control Block (DCB) is a block of storage that is the highest level data 
structure for each user on the PS 300 system. There is one DCB for each user. The DCB 
is linked to the topmost nodes for all of the data structures associated with the user. The 
DCB is shown in Figure 2-7. 
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Next DCB 


Pick Select List Head 


Allocate Plotter 


Plotter Select 


First Set 


Pick Block Pointer 


Pick Index 


Pick Count 


Pick @ Block Pointer 


//////////////// 


Data Type 


0 


Exponent / Vector Type 


Rcked X 


Picked Y 


Picked Z 


Curve parameter t 


Curve segment number 


Rsvd for Future Enhancements 


Rsvd for Future Enhancements 


Rsvd for FuUire Enhancements 


Rsvd for Future Enhancements 


LP Status 


Unused Word 


Light pen X position 


Light pen Y position 


Menu Function 


Pick Function 


Timeout Function 


Lightpen Function —-j 


User Suffix 


//////////////// 


Menu Copy 



Figure 2-7a. DCB Block 
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TYPE 

Int8 

PtrDCB 

Ptmamedentity 

Ptxalphablk 

Deb 

RECORD 


-128..127 
DCB; 

"'Namedentity; 

"Alphablk; 


Nxt: Ptrdcb; 

Picklh: Integer; 

Plotallocate: Bitmask; 
Plotterselect: Bitmask; 

Firstset: Ptralphablk; 
Actual_pblock: Ptmamedentity; 
Pickindex: Inti6; 

Pickcount: Inti6; 

Pickblock: Ptralphablk; 
Dcbpadl: Int8; 

Picktype: Dattype; 

Dcbpad2: Intl6; 

Pickexp: Int8; 

Vectype: Int8; 

Pickx: Inti6; 

Picky; Inti6; 

Pickz: Inti6; 

Tsegments: Inti6; 

Curvet: Intl6; 

FI: Integer; 

F2: Integer; 

F3: Integer; 

F4: Integer; 

LPTStat: Bitmask; 
jdpad : Intl6; 

LPXcen: Inti6; 

LPYcen: Intl6; 

Menufen: Ptmamedentity; 
Pickfen: Ptmamedentity; 
Timoutfen: Ptmamedentity; 
LPfen: Ptmamedentity; 

^ Usersfx: char; 

Menucopy: integer; 

END; {of DCB} 


(Next on list} 

(Pick list head (really ptmamedentity)} 

(Bit 11=1 if plotter allocated} 

(Bits 9..8 select plotter—used only by GCP} 
(Pointer to alpha of set} 

(Actual block picked} 

(Pick index field of picked node} 

(Vector count of pick} 

(Picked block} 

(Dattype of picked node} 

(Exponent of coordinates} 

(Vec type of picked vec} 

(x,y,z of picked vec} 

(number of segments used for t} 

(Curve parameter t with jimk} 

(Reserved for future} 

(Reserved for future} 

(Reserved for future} 

(Reserved for future} 

(Lightpen status} 

(Pad to 0 mod 4 for ACP} 

(Light pen X center, exp = 0} 

(Light pen Y center, exp = 0} 

(fen waiting for menu pick} 

(fen waiting for pick} 

(Fen to handle ACP timeout} 

(fen to handle light pen} 

(user suffix char, this DCB} 

(copy of Menunum at Menu time} 


Figure 2-7b. Pascal Data Definition of DCB Block 
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Details of the Data Control Block are explained below: 

- Next DCB 

The next DCB pointer (Nxt) is an address in Mass Memory of the next DCB on the 
DCB list. In multiple user environments, a DCB exists for each user. The ACP 
traverses the DCB blocks (and associated display data structures) until it encounters a 
next DCB pointer that is zero. For a single user, the next DCB pointer is always zero. 


- Pick Select List Head 

The ACP may encounter pick identifier nodes during traversals of the display data 
structures. The Pick Select List Head (Picklh) is a pointer to the Mass Memory 
location where the ACP last encountered a pick identifier node. 


- Allocate Plotter 

The GCP sets bit 11 in this field if the user associated with this DCB has allocated the 
hard-copy device. Note that only one user can request a hard copy at one time. 
Other bits in this field may be used to communicate to the ACP. 

- Plotter Select 

Bits 8 and 9 in this field keep track of which hard-copy device the user has selected. 


- First Set 

First set (Firstset) is an indirect address in Mass Memory of the topmost node of all 
the data to be displayed for the workstation associated with this DCB. The node, or 
one of its descendants, is expected to contain members for each of the user display 
modes (i.e., Graphics, Terminal Emulator). 


- Pick Block Pointer 

After a pick has occurred, this field contains a pointer to the block whose vector or 
character was picked. 

- Pick Index 

The pick index (Pickindex) is a 16-bit integer associated with a vector or character 
list, indicating which list contained the picked vector or character. 


- Pick Count 

The pick count (Pickcount) is an integer indicating which vector or character was 
picked, respectively, in a vector or character list. This count is valid only when the 
pick select listhead is non-nil. 
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- Pick @ Block Pointer 

After a pick has occurred, this field contains a pointer to the alpha block of the node 
whose vector or character was picked. 


- Data Type ^ 

After a pick has occurred, this field contains a value indicating the data type of the 
vector or character list in which the pick occurred. 


- Exponent, Vector Type, Picked x, Picked y. Picked z 

These fields give the x, y, and z values of the point which was picked and provide 
information,in the Vector Type(Vectype) field, concerning the state of the pick. For 
example, if an error occurs in determining the x, y, and z values, the ACP sets bit 7 of 
the Vectype field. Also, if no x, y, z values are to be returned (for example, for a 
character pick), bit 3 of the Vectype field is set. 


- Curve parameter t 

This field gives a coimt used to compute the (x,y,z) of the picked point as a fraction of 
the vector when the vector is part of a curve definition. 


- Curve segment number 

This is number indicates number of segments that the 3-D picking microcode has 
divided the original picked vector to find the 3-D coordinates. 


- LP status: k 


1 . 

2 . 

3. 

4. 

5. 

6 . 

7 


8 . 

9. 


10 . 

11 . 

12 . 


13. 

14. 

15. 

16. 


Bit 15 — Screen blast found a pick in the last frame. 

Bit 14 — Set if tip switch was pressed in the last frame. 

Bit 13 — Tracking cross found a pick in the last frame. 

Bit 12 — Not used. 

Bit 11 — Not used. 

Bit 10 — Set if the user specified (X,Y) coordinate is used to position a tracking 


cross. 

Bit 9 — Set if screen blast enabled. 

Bit 8 — Set if a tracking cross enaSied. 

Bit 7 — (Set if the debug mode enabled) 

Bit 6 — Set if the user has NOT triggered this operate node. 

Bit 5 — Set if the GCP wants the ACP to display only a tracking cross. 

Bit 4 — Set if the delta limit has been exceeded. 

Bit 3 — Set if tip switch changed from NOT pressed to pressed. 

Bit 2 — Set if tip switch changed from pressed to NOT pressed. 

Bit 1 — Set if the ACP has updated this word. Set if clock is to schedule LPIN 
function 

Bit 0 — Set if the ACP has updated this word. 
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Bits 15 through 5 are written by the ACP to the matrix memory to the store the status 
of the light pen operation to be used the next frame, when it traverses the light pen 
operate node. Bit 4 is set to indicate that the current tracking cross location has 
changed more than the delta from the previous location. Note that the previous 
location is updated only if the new X and Y is specified or above condition is met. Bit 
3 is set if the tip switch status is changed from NOT pressed to pressed. Bit 2 is set if 
the tip switch status is changed from pressed to NOT pressed. Bit 1 and 0 are set if 
EDGE = TRUE or EDGE = FALSE and/or LP DELTA condition is detected and 
also the GCP has reset the ACP ACTION bit when the light pen operate node is 
traversed. 


- Light pen X position, Light pen Y position 

Contains the current location of the center of the lightpen tracking cross. 


- Menu Function 
Not currently used. 


- Pick Function 

The pick function (Pickfcn) is a pointer to the pick function instance which is 
activated when a pick occurs (when the pick listhead is non-nil). This field is known 
only to the GCP. 


- Timeout Function 

Time out function (Timoutfcn) is a pointer to the user timeout function, which is 
activated when the ACP requires too much time to traverse the display data structures 
( usually indicating a recursive display structure). The user timeout function removes 
all user-created display data structures from the display. Note that this field is known 
only to the GCP. 


- Lightpen Function 

The lightpen function (LPfcn) is a pointer to the lightpen function instance which is 
activated when a change in lightpen status occurs. 


- User Suffix 

The user suffix (Usersfx) is a character which identifies the user associated with this 
DCB. This field is known only to the GCP. 


- Menucopy 

Not currently used. 
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2.2.2.2 Set Node 


A set node is a data structure that can contain a variable number of members, each of which is, in 
effect, a set node, operate node, or a data node. Each member of the set is processed 
independently from every other member. That is, the state of the ACP is guaranteed to either be 
saved before each member of the set is traversed and restored afterwards or to remain unchanged 
by the member of the set. As Figure 2-8. shows, a set node consists of: 

• Set Node Indicator 

The set node indicator is a value (=0) that identifies this Named Entity as a set. 


• ACP Save State Pointer 

The ACP save state pointer is an address in Mass Memory of the location where a block 
of storage has been allocated for the saving of the ACP state information. If this address 
is zero, the ACP state is not to be saved for this set. 

• ACP Control Block Listhead 

The ACP control block listhead is an address in Mass Memory where the first ACP 
control block associated with this set resides. An ACP control block exists for each 
member of the set. 


• ACP Control Block Listtail 

The ACP control block listtail is an address in Mass Memory where the last ACP control 
block associated with this set resides. This is always a dummy control block (the alpha 
pointer is always null). It is there because the ACP writes into its NEXT pointer to aid in 
structure traversal. The GCP is not allowed to remove this control block. 

• GCP Control Block Listtail 

This control block is the last real control block. The ACP does not know about this field. 
It is there so that the GCP can add control blocks to the end of the list of control blocks 
without walking through the entire list of control blocks. 
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CONST 

Netyp 

TYPE 

Ptrsavstate 

PtrACPcblk 

Ptralphabik 

IntS 

Intl6 

Namedentity 

RECORD 


0 : 

^Savstate; 
-'ACPcblk; 
■'Alphablk; 
-128..127; 
-32768..32767; 


Notused: Int8; 

CASE Typ: Netype OF Setnode; 
Notused2; Intl6; 

Ss: Ptrsavstate; 

Lh; PtrACPcblk; 

Lt: PtrACPcblk; 

Actlast: PtrACPcblk; 

END; 

ACPcblk 

RECORD 


Nxt: PtrACPcblk; 
Alpha: Ptraiphablk; 
Ss: Ptrsavstate; 
END; 





Figure 2-8. Set Nodes and Pascal Data Definition 
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- ACP Control Blocks 

As figure 2-8 shows, each set consists of a variable number of ACP control blocks, linked 
together as a list that will be traversed by the ACP as the set is processed. An ACP control block 
exists for each member of a set. Each ACP control block consists of: 


• Next ACP Control Block Pointer 

The next ACP control block pointer (Nxt) is an address in Mass Memory of the next 
ACP control block to be processed after the display data structures associated with this 
ACP control block are traversed. (Refer to “Alpha” below.) 


• Alpha 

Alpha (Alpha) is the indirect address in Mass Memory of the display data structures to be 
traversed as this member of the set. 

• ACP Save State Pointer 

The ACP save state pointer (ACPstate) is an address in Mass Memory where the current 
ACP state resides. This state must be reloaded by the ACP before traversing the 
descendant display data structures of this block. If the ACP save state pointer is zero, 
then the ACP state has remained unchanged from the last time it was loaded. For 
example, the first ACP control block of a set will always have an ACP state pointer of 
zero, since the ACP save state is the current state, by definition. 


When the ACP encounters a set, the last ACP control block of that set (the one pointed to by the 
ACP control block listtail) is updated to point to the next ACP control block to be traversed when 
that set is completed. The ACP then traverses the set. When the last ACP control block of the 
list is traversed, the updated next-ACP-control-blockpointer then directs the ACP to the next 
ACP control block. 


2.2.2.3 Operation Node 


An operation node is a data structure that modifies the state of the ACP. As shown in Figure 
2-9, an operation node consists of an integer that indicates this display data structure is an 
operation node (=1), an integer that specifies the particular type of operation node, the 
descendent alpha, and a variable number of fields required by the particular type of operation 
node. Because an operation node modifies the state of the ACP, the ACP state must be saved 
before traversing a member of a set whose descendants include an operation node, and be 
restored before traversing the next member of the set. For any operation node, bit 15 of the 
operate type is a Conditional bit. If this bit is set, and if bit 15 (the blink bit) in the Condition 
Mask of the ACP State is zero, then the associated operation node is not performed. In all other 
cases, the operation node is performed. In all cases, the son of the operation node is traversed. 
Each of the operation nodes is described in Appendix J. 


\ 
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NOTE 

A “C” in the left comer of the Operate Type block indicates the 
Conditional Bit (bit 15). 




Figure 2-9. Operation Node 


2.2.2.4 Data Node 

A data node is the display structure primitive that causes data to be drawn by the ACP. A data 
node consists of an integer that indicates this display structure is a data node (=2), an 8-bit field 
that specifies the mode of vectors in the data node, an 8-bit integer that specifies the particular 
type of data node, a 32-bit integer which points to the next data node of identical data type, an 
integer (n) that specifies the number of vectors, polygons or characters in the data node, a 16-bit 
integer that specifies the pick index, and either vector data (including polygons) or character 
data. Vector data consists of the two- or three-dimensional vectors (preceded by polygon 
attribute information if polygons). Character data consists of an initial translation, spacing 
information, and the character string. The general format of a data node is illustrated in Figure 
2-10. The format for each of the data nodes is shown in Appendix J. 




Figure 2-lOa. Data Node 
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TYPE 

Namedentity = RECORD 

Not used: Int8; 

CASE Typ: Netype OF 
ACPdata: (Do_Dots: Boolean; 
Adson: Ptmamedentity; 
Adnum: Inti6; 

Adindex: Inti6 
• 

• {Data} 


); 

END; 


Figure 2-lOb. Pascal Data Definition of Data Node 



Mode, data type, pick index, and vector/character data are detailed further below. 
• Do_Dots Field 

The Do Dots field of a data node consists of: 


Unused 


D 


Data Type 


Do_Dots Field-' 

= 0 for no endpoint intensification 
= 1 for endpoint intensification 


The Do^Dots field of a data node is a single bit that specifies how the vectors are to be 
drawn. When dot mode = 0, vectors are drawn normally. When dot mode = 1, each 
endpoint of the vector list is drawn as an intensified dot. 


• Data Type 

The data type field specifies the particular format of the data node. The ACP in the 
PS 300 accepts vectors of two formats: 



1. Vector-normalized data (full vectors) 

Vector-normalized data consist of 16-bit, signed binary fractions that share a 
common 8-bit, signed integer exponent and an explicit 7-bit, intrinsic intensity for 
each vector. 
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For the vector: 

(xj,zJ) X = 2^ * fx, y =2^ * fy, z - 2^ * fz, i = i 

where e is the signed 8-bit integer exponent; the 16-bit significant digit fields fx, fy, 
and fz satisfy -1 < / < 1; and the 7-bit intrinsic intensity field i satisfies 0 < / < 
LVectors contained within polygon nodes consist of 3D vector-normalized data as 
described above. 


2. Block-normalized data 

Block-normalized data consist of 16-bit signed binary fractions that share a common 
7-bit signed integer exponent and an explicit 8-bit intrinsic intensity for each block of 
vectors. For the vector: 


Xj= 2^ • fxi, 

yi= 2^ • fyi, 

Zi = 

2^ * fzi, 

i = / 

X 2 = 2^ * fx 2 , 

• 

y 2 = 2^ * fy 2 , 

Z2 = 

2^*/z2, 

i = / 

• 

• 

x„= 2^ • fXn, 

A 

« 

rN 

II 


2^*fZn, 

/ = i 


where e is the signed 8-bit integer exponent; the 16-bit significant digit fields fx, fy, 
and/z satisfy -1 < / < 1; the 7-bit intrinsic intensity field / satisfies 0 < / < 1. 

The PS 350 also accepts two formats; They are the 16-bit block-normalized format 
shown above and a 32-bit block-normalized format that is the same in computation 
except that fx, fy, and fz are 32-bits instead of 16-bits. 

• Next Data Node Field 

The next data node field contains a 32-bit pointer to the next data node of identical type 
(0 = nil pointer). This pointer allows vector lists to exist in non-contiguous blocks of 
memory and also allows one to group a set of character strings together (Label Block). 

• Pick Index Field 

The pick index field of a data node is reported with the vector count when a pick occurs, 
thus signifying the vector list in which the pick occurred. Although the number of vectors 
that may be contained in a data node is 65,535 (if n is treated as a 16-bit unsigned 
number), by convention, the maximum number of vectors that will be specified in a given 
data .node is 2048, which is less than the maximum number of vectors that may be 
counted during pick processing. The software that creates data nodes will ensure that the 
index is correct for a given data node and that the reported index, together with the 
vector count, will allow one to correctly identify the actual vector that was*picked. 
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• Vector or Character Data 

- Vector Data 

All vector data processed by the ACP are numbers of normalized, floating-point form, 
as 2^ * / , where ^ is a signed-integer exponent and the significant digit field, /, 
satisfies -1 < / < 1. Rather than provide an exponent for each coordinate of a vector, 
the Display Processor associates a single exponent with each vector or block of 
vectors. All vector data are two- or three-dimensional (i.e., (x,y) or (x,y,z)), with an 
implicit, homogenous coordinate equal to 1 (i.e., (x,y,z,l)). The dynamic range 
gained by explicit use of the homogenous coordinate has been provided by 
representing vector data in the normalized, floating-point form. In addition, polygon 
vectors have implicit closure; that is, there is an implied vector from the last point of 
the polygon to the first point. The ACP automatically displays this implied vector. 

- Character Data 

Character data consist of an initial translation to position the character string, spacing 
information to control the spacing between characters, and a string of characters. The 
initial translation consists of 16-bit, signed binary fractions for x, y, and z, with an 
implicit, homogeneous coordinate equal to 1 (i.e., (x,y,z,l)), and a shared 8-bit, 
signed integer exponent. Thus, the translation: 

(xj.zJ) x-2^*fx, y-2^*fy, z=2^*fz, 

where e is the signed, 8-bit integer exponent, and where the 16-bit significant digit 
fields/x, fy, and fz satisfy -1 < = f < 1. The spacing information consists of a delta x 
and a delta y, each a 16-bit, signed binary fraction, sharing an implied exponent equal 
to zero. The delta x and delta y values determine the separation between characters 
in the x and y directions. They are given in the coordinate space of the characters 
themselves, satisfying the range: -1 < = delta jc, delta y < 1. 

For each character in a string of characters, the corresponding character stroke block 
is read from Mass Memory to provide the vectors which make up the individual 
character. The format of this character stroke block is described in Section 2.2.3. 


2.2.3 Character Font Block 

Each entry of the character font table is a 32-bit address in Mass Memory indicating where the 
associated character stroke block resides. Each character stroke block is an abbreviated Vec2s0 
block, consisting of a coimt of the number of vectors followed by the Vec2s0 vectors. Note that 
this type of data block is used only in association with the character font block. 

The character font block and associated character stroke blocks (with strokes in relative mode) 
are shown in Figure 11. The x and y components of each vector are 7-bit binary fractions that 
have an implied exponent of 0. 
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PtrVec2sblock = Integer; 

Ptrqdata = *Qdata; 

Charfont = 

RECORD 
Fontsize: Int 16; 

CASE Chars: Chsize OF 

C128: (Ccd: ARRAY[0..127] OF PtrVec2sblock); 
C256: (Cnd: ARRAY[0..255] OF PtrVec2sblock); 
END; 

Vec2sblock = 

RECORD 
V2smim : Inti6; 

V2s : ARRAY [1..1] of Vec2s0; 

END; 

Vec2s0 = 

RECORD 
X : Int8; 
y : Int8; 

END; 




Figure 2-11. Character Font Blocks and Pascal Data Definition 
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2.3 Commhead 

The largest portion of global variables used by the PS 300 exists in a record called Commhead. Its 
format can be seen in the Appendix I. This block, located at the low end of Mass Memory, 
contains pointers to the active and priority function lists, the various update lists, the standard 
character font, the hashtable, the command and function name dictionaries, and the initial Save 
State, as well as to other information. 


2.4 Number Formats 

The intrinsic data types utilized by the Graphics Control Program are: 

• IntS: 

an 8-bit, two’s complement number in the range of -128 to +127. 

• Intl6: 

a 16-bit, two’s complement number in the range of -32768 to +32767. 

• Integer: 

a 32-bit, two’s complement number in the range of -2147483648 to +2147483647. 

• Double: 

a 40-bit precision, floating-point number consisting of an 8-bit exponent (or 
characteristic) and a 32-bit fraction (or mantissa). 


2.5 Hash Table 

The hash table is an array [-l..n] of pointers to forward and backward linked lists of alpha 
blocks. The value of n is based on the amount of mass memory available when the system boots. 
This value is contained in the Commhead. 

Naming a node causes the name to be entered into the hash table with a pointer to the Alpha 
block associated with that name in PS 300 Mass Memory. The -1 entry in the table is for 
forgotten Fcninstances since their connections must be found when doing an INIT CONN; 
command. 

Any time a name is used in the system to reference a structure the name is processed by a hash 
algorithm to produce a hash index. This number is the index into the hash table. The Alpha 
pointer at that index is checked to see if the name equals the requested name. If not, the 
dictionary forward pointer of the Alpha is then checked. This process of checking continues until 
the name is found or the linked list ends. 
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3.1 Structure Creation 


There are four main steps in the creation of structures in the PS 300. 



1. Alpha Lookup 

2. Named Entity Creation 

3. GCP Datum Pointer Set 

4. Alpha Update 

3.1.1 Alpha Lookup 


A lookup of the name specified is done which returns with a pointer to the Alpha block of 
the specified name. If the name wasn’t already in the dictionary, it is added during the 
lookup. 


3.1.2 Named Entity Creation 

After the Alpha is established, the actual Named Entity structure is created. If the 
Named Entity is a function instance, there is a check of the function table to determine if 
it is a valid function. If it is valid, a check is made of the number of inputs and outputs to 
allocate in the function block. At this point the initialization code is executed and the 
state of the function is set to ACT ON UPDATE. If the Named Entity is a display 
structure, a Named Entity block of the proper type is created and data is put into the 
structure. 


3.1.3 GCP Datum Pointer Setup 

A pointer to the Named Entity is placed in the GCPdatum of the Alpha block. 
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3.1.4 Alpha Update 

Pointers to the Alpha block and the Named Entity are placed on the AGP update list that 
causes the change to take place at the end of the current structure traversal. 


3.2 Update Process 

The GCP creates and manipulates the display data structures in mass memory (and 
initiates the display defined by these data structures). The AGP then accesses the data 
structures in Mass Memory, traverses the structures, and transforms the data to be 
displayed. A rigid update process is followed when modifying display data structure. This 
process ensures that the GGP won’t corrupt a data structure being traversed by the AGP 
and that changes in the display data structures will be synchronized. The update process 
entails: 

1. A function produces a private list of changes through calls to Lgaupdate and 
OLbaddtoset. This creates a list head and tail pointer containing the private list of 
updates. Each call to Lgaupdate or OLbaddtoset adds to the list until a call to 
Announceupdate is made. The list tail is used in calls to FetchBlock, FetchAdnum 
and nFetchGopy to allow the searching of the private list for matching Named 
Entities. 

2. The function hands the private list to the update formatter. This list is made available 
by a call to Announceupdate. This call gives the functions private list to the update 
formatter to be added to the current global list of updates to the AGP. 

3. The AGP makes the changes specified in the global list at the end of a refresh cycle. 
The AGP processes the list of changes and performs all updates. 

4. The GGP post-processes the update blocks. After the AGP finishes the update list, the 
blocks of data are returned as available storage. 


Because the display data structures are constantly being traversed for display by the AGP, 
whenever a change is required to a node the GGP “usually” makes a copy of the node 
that is to be changed, changes the elements to be changed, and then simply causes the 
pointer to the node in the alpha block to be changed by the AGP after it has finished 
refreshing. This occurs whenever a matrix is changed, a new PS 300 display enabled, etc. 
In essence then, most changes to the display data structures cause the change to be 
“double buffered” until the change can take place. Such changes are made by the AGP 
at the end of each refresh cycle. 
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The GCP creates an update block whenever display data structures require updating by 
the AGP. Basically, an update block indicates what changes need to be made and where 
these changes are located in Mass Memory. The update block also specifies what TYPE 
of update is to be processed. The AGP can process two types of update blocks: 

• Alpha update 

• Value update 


3.2.1 Alpha Update 

An alpha update is performed whenever an alpha block is to refer to a new Named Entity 
block. Except for minor changes in data nodes, most updates in the standard runtime 
system are alpha updates. For example, all operation nodes are updated by creating a 
new operation node with the correct contents, then performing an alpha update. 


3.2.2 Value Update 

A value update is performed whenever a value is to be updated in an already existing data 
structure, i.e., whenever small portions of a data structure (e.g., character(s) or 
coordinates of a point) need to be updated in place without copying the entire data 
structure. 


3.2.3 AGPProof 


The updates process is not universally followed. A technique, called AGPproof, was 
established for special cases when direct modification by the GGP of the data structure 
(without going through the normal update process) is needed. If the GGP makes a change 
to a data structure through the normal update process, a Named Entity can NEVER be 
expected to be in the same location in Mass Memory. However, conversely, garbage 
collection is never done on existent Named Entities by the PS 300. So once a node has 
been created, if the node is NEVER referenced by a standard PS 300 function network or 
externally from the host, a Named Entity can ALWAYS be expected to be in the same 
location in Mass Memory. This knowledge can sometimes be used in a user-written 
function or by physical I/O programmers. 

For example, values in the node can be changed directly. However, if the node is 
currently being displayed no guarantee can be given that the AGP will not traverse the 
node during the small, but finite, time frame during which the data may be changed. This 
may result in an improper picture being displayed (new x value, old y value; or a matrix 
with mixed values—part new, part old) but should never cause the AGP to traverse the 
display data structures improperly. As Long As No Pointers Are Ghanged. Any pointers 
which are to be directly changed in the data structure by the GCP should use AGPproof. 
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ACPproof uses a convention with the ACP that if the top half of a pointer is zero, the 
pointer should be treated as nil. (ACPproof works by zeroing the upper half of a pointer, 
changing the lower half, and then changing the upper half. In this way the ACP either 
gets the old pointer, gets the ACPproofed pointer with a zero upper word, or gets the new 
pointer.) Not all pointers can be modified in this way. The ones which can be used with 
ACPproof are: 

• Nxt in the DCB 

• Firstset in the DCB 

• Nxt in Acpcblk 

• Alpha in Acpcblk 

• Aoson in Acpoper 

• Adson in Acpdata 


3.2.4 Use of RAWBLOCK 


The RAWBLOCK command is used to allocate memory that can be directly managed by 
a User-Written Function or by the physical I/O capabilities of the Parallel Interface. 

The command: 


name := RAWBLOCK i; 

carves a contiguous block of memory such that there are “i” bytes available for use. 
Since this has to be a display data structure and one contiguous memory block, it is 
structured so that it appears as shown in Figure 3-1. 



= Nop 

Points to next long word 
Initially NIL 


Figure 3-1. Rawblock 
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This block looks like an operation node to the ACP. The descendant alpha pointer 
points to the next long word in the block. What the ACP expects in this word is the 
datum pointer of the alpha block. This is initially NIL to make the ACP think that the 
alpha doesn’t have any data associated with it yet. To use this block, the parallel interface 
or a user-written function fills in the appropriate structure following the datum pointer. 
When this is complete, it changes the datum pointer to point to the beginning of the data 
using ACPproof. 


More than one data structure at a time can exist in a RAWBLOCK. It is up to the user to 
manage all data and pointers in a RAWBLOCK. A RAWBLOCK may be displayed or 
deleted like any other named data structure in the PS. 300 (e.g., DISPLAY “name”; or 
DELETE “name”;). 


3.3 Function Operation 

The PS 300 functions are instances of “generic” functions which exist in the PS 300 
runtime system. Generally, a generic function is a Pascal procedure which performs one 
or more operations by (a) accepting input, (b) processing input, and (c) sending output. 
(Note that occasionally the function code is written in assembly language but is called as a 
Pascal procedure.) The user, or less commonly the runtime software itself, creates a 
PS 300 function by “instancing” a generic function. There may be many “instances” of 
the same generic function. Each instance has its own user- or system-defined name, as 
well as its own input queues and output connections. The user connects these function 
instances into a network. Thus, each PS 300 function generally has inputs coming from 
other functions and outputs going to other functions or data structures. All information 
regarding the instancing of a function, as well as all information regarding connections 
between instances, is kept in a “function instance block” and its associated substructures. 


When a function instance is created, it is assigned a default priority for execution (most 
default to 8). The Scheduler uses priority numbers to determine which of the PS 300 
functions awaiting execution will be executed next. It executes a function by placing a 
pointer to the function instance block and calling the Pascal-callable procedure for the 
generic type of the function instance. 


A function instance cannot be executed until all of its essential inputs have arrived. 
Inputs exist on (and outputs are sent to) input queues. Once the function has processed 
the inputs, any output values are sent to destinations listed as outputs of that instance. 
Some functions may wait on an I/O device rather than on an input queue. In this case, 
the I/O device interrupt routine activates the function at the proper time. The following 
sections detail the creation, manipulation, scheduling, and execution of function 
networks. 
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3.3.1 Scheduler 

AltJiough it is not the major portion of code, the Scheduler is the driving force behind the 
Graphics Control Program. The scheduling loop is the process by which the Scheduler 
executes activated functions. Executing a function means to place the address of the 
function instance block in a global variable and call the generic Pascal procedure. 

The Scheduler is designed to avoid two major sources of lost time in software-scheduled 
systems: task context switching and the scheduling decision itself. Time can be lost in 
context switching, i.e., when a program is interrupted, because the complete processor 
state (including any memory mapping state) must be saved and the state of another task 
must be put in its place. 

The Scheduler avoids this loss in processing time by assuming that all scheduled functions 
will run to completion once execution begins. This assumption is based on the constraint 
that all functions complete in a reasonable amount of time, i.e., less than two 
milliseconds. If an operation could take much longer, the function must place all data on 
a private queue and reschedule itself for execution. Note, however, that because this 
saving, restoring, and reschedxiling process is so time-consuming, some functions are 
allowed to continue running. 

Because of the large amount of time to schedule a function instance, most functions are 
allowed to process more than one set of inputs per wakeup if a global Boolean variable 
KEEPGOING is true. This variable is set to be true by the scheduler prior to executing a 
function. However, any time the clock interrupt routine sees that a function waiting on 
the clock is ready to run, it can potentially set KEEPGOING to be false. Once 
KEEPGOING is false, the currently running function must give up control prior to 
processing the next set of inputs. 

Time would also be lost in scheduling decisions if the Scheduler scanned all potentially 
active tasks to determine which were truly active. Therefore, the Scheduler loop scans 
only those functions that are part of an active list. When a function instance is created, it 
is assigned to one of 16 possible priority levels (0-15). The priority level is used by the 
Scheduler to determine when the function instance will execute. Unless mass memory is 
nearly full, priority is such that the smaller the priority number, the earlier the function 
instance is executed. Most functions operate at priority level 8. If mass memory is nearly 
full, the Scheduler executes only functions which do not require additional mass memory. 


At each execution, the Scheduler empties the Active List (the list of functions to be 
executed) into a set of separate lists (according to priority). It then executes the first 
function on the highest priority list. After the function has been executed, control returns 
to the Scheduler and the process is repeated. Note that user commands do exist to change 
a function’s priority level. However, if a function is already on an active list when its 
priority is changed, the function’s scheduling position does not change until subsequent 
activation. 
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3.3.2 Function Activation 


Function instances are “activated” when they are placed on the Active List. The 
Scheduler then processes the Active List and executes the functions. Once a function has 
been instanced, it must have received all of the inputs needed for execution in order to be 
activated. During function instance creation, the function instances are initialized if 
necessary. This generally means that default values are placed on some input queues, 
and the private data message is created and initialized. Function instances are first 
activated following function instance creation. The first time it is executed a function will 
cause itself to do one of the following: 


• Be reactivated. 

• Wait for an input on one or more input queues. 

A function waits for input on its queues by setting the Numnonnull counter in its 
record block to indicate the number of necessary input queues which still remain 
empty. Whenever another function sends data to an input queue, if that queue does 
not already contain data (hence one more necessary queue now has data), the 
numnonnull counter is decremented. When this counter is decremented to zero, the 
function is placed on the active list by the procedure doing the message send. 

• Wait for the clock or an I/O event. 

If a function instance has an output designation and is ready to send a message to another 
function, it does so by: 

• Obtaining a Qdata block from free storage and creating the message. 

• Sending the message to the destination specified in the function block’s 
outdesignator. Utility procedures exist to do this. 


3.3.3 Function Status 


At any given time during its instancing or activation, a function exists in one of several 
possible states. Those states are: 

1. Actonupdate 

When the function is instanced. Once it has been tied to its name by the AGP, it 
takes on Active status. 

2. IO_wait 

When the function is waiting for input from an I/O device or waiting to be activated 
by the clock. 
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3. Msg__wait 

When tJie function is waiting for input on one or more input queues. 

4. Active 

When the function is on the Active List (waiting to be executed). 

5. Running 

When the function is being executed by the Scheduler. 

6. Self_destruct 

When the function is to be destroyed, rather than executed, the next time it is 
scheduled. 

Note that before a function is executed, the Scheduler changes its status to Running. A 
fatal system error occurs if control returns to the Scheduler after execution and the status 
is still Running. Thus, a function must cause its state to change during execution by either 
(a) waiting on a device or queue, or (b) activating itself, or (c) setting its status to 
Self-destruct and then activating itself. 

A function cannot wait on more than one item (queue, clock, or I/O device). Thus, a 
system error also results if a function waits on a device, clock or input queue and then 
attempts to wait again without first changing its own state. 


3.3.4 Function Code Format 

The Pascal-callable procedure defining the generic function generally follows a rigid 
framework. It usually has a single parameter, which is a pointer to the function instance 
block of the particular function instance. A typical function procedure includes 
instructions to do the following: 

1. Check input queue(s) for new data. If there is a complete set, go to step 2. If not, set 
status to wait for data to be sent to empty queues and return to the Scheduler. 

2. Take one set of input data from the input queues (buffer). 

3. Use that data to modify the private data, display structures, and/or generate output 
messages as needed. 

4. Send any output messages to all destinations referred to in the function instance 
block. 

5. Check the input queues for another sufficient set of data. If it exists, and the global 
flag Keepgoing is still set, then proceed to Step 2. If Keepgoing is False, then queue 
self on the active function list. If a sufficient set does not exist, set status to wait for 
data to be sent to empty queues and return to scheduler. 


3-8 


PS 300 Advanced Programming 




MODULE 4 



Physical I/O Programming 



The PS 300 is designed primarily to meet the needs of those customers who require that the 
dynamics of picture display be handled on the local PS 300 level, rather than be tightly coupled to 
a host machine. This is possible through the means of function networks, which offer a selection 
of local actions, driven by peripheral devices such as the dials or data tablet, or simply by 
internally-generated time pulses. This removes most of the frame-by-frame load from the host, 
freeing it for other work. However, there remain many applications where the host itself may be 
required to closely direct — perhaps even on a per-frame basis — the dynamics of the displayed 
picture. The difficulty in meeting this requirement has to do not only with the overall software 
speed, but with an inherent limitation of the hardware; namely the narrow bandwidth of the 
commimication channel from the host to the PS 300. Because it was intended that 
frame-by-frame dynamics be handled on a local level, the asynchronous interface was not 
designed for host-driven dynamic communication. To circumvent this problem, and to provide 
for efficient host direction of dynamic operations, the system function FrUSERUPD was provided. 


4.1 The F:USERUPD Function 


This function permits a variety of dynamic transformations to be sent from the host each 
frame, directly effecting changes to the displayed picture on a per-frame basis. Only the 
arguments for these transformations are sent, with the matrices and vectors being 
generated by the F:USERUPD function, thus greatly decreasing the bandwidth 
requirements of the communication line. For example, the dynamic arguments for a 
picture with 25 to 30 degrees of freedom may be sent at a 10-hertz update rate over a 
9600-baud, asynchronous line. The F:USERUPD function, however, has some 
limitations both in system response speeds, and in flexibility. The ability, for instance, to 
turn a portion of the picture on or off using level-of-detail or conditional bits is not 
available with this function. Refer to the PS 300 Document Set Volume 4, Other Tools, 
for more complete details of the USERUPDATE function. 
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4.2 The Parallel Interface 

In order to help meet the need for more closely-coupled host control of the PS 300, a 
16-bit-wide parallel interface, operating through the General-Purpose Interface Option 
(GPIO) was developed. This interface gives VAX users a much higher data transmission 
rate, on the order of 0.5 megabytes per second (in practice the rate is somewhat less, and 
depends on cable length). This is still many times faster than the 56 kilobaud runner-up. 

The effective speed of this interface is so great, that it outstrips the ability of both VAX 
and PS 300 software to keep up with it. The Graphics Support Routines (GSR's), for 
example, must issue a separate System I/O Request (QIO) for each message to be sent to 
the PS 300. These requests are queued up to await the attention of the parallel interface 
device driver, and the more queued-up QIO’s, the slower the response. In addition, on 
the PS 300 side, the incoming messages must each go through the command interpreter, 
generating new data nodes and involving other overhead having to do with the data 
structure. 


4.3 Physical I/O 

To fully take advantage of the speed of the interface, and to eliminate as much of the 
node-juggling and other overhead as possible, the parallel interface protocol (and 
especially the GPIO microcode) includes, in addition to the standard communication 
commands, another set of commands collectively referred to as physical I/O commands. 
These commands permit the host to directly access the internal contents of any node (or 
other PS 300 structure, for that matter), and modify those contents at machine speeds, 
without any node swapping, pointer juggling, memory management, or command 
interpretation. 


This direct access is possible because one of the physical I/O commands allows you to give 
the ASCII name to the PS 300 of any node, and receive back the physical memory 
location of that node. Once this address is known, and you know the internal structure of 
the node, you may use the Write Physical command to directly modify those contents to 
suit your needs. 


In addition, physical I/O includes the capability of scatter-writing from a single buffer into 
many non-contiguous blocks of PS 300 memory, thus allowing a single host QIO to 
effect modification of all the dynamic updates for an entire frame. 
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4.3.1 Physical I/O Constraints 


Because of the ability of physical I/O to circumvent the normal protocol of node- and 
structure-building by addressing any desired PS 300 mass memory location, you must use 
considerable caution in selecting the memory areas you choose to modify. You must 
consider the following rules to avoid crashing the PS 300 or worse by causing a bug which 
may appear later. These rules are: 

1. Only the contents of AGP data structures (i.e. nodes) can be modified. Modification 
of any other areas of memory is not allowed. 

2. Only the DATA portions of the nodes can be modified. The STRUCTURE elements 
(in paiticxilar, the first four 16-bit words of each node) must never be modified. 

3. Because the system modifies a node by making a copy of it in another place, 
modifying the copy, and then changing pointers, you must NEVER modify a node 
which can be modified by another source (for example, one that is referenced by a 
function network). 

4. Note that the Graphics Display Processor (the ACP) is also traversing the data 
structure at the same time your buffer is being written into it via physical I/O. A 
“double- buffering” scheme must be implemented to avoid the chance of the ACP 
trying to access YOUR node while YOU are writing into it. Refer to 4.4 below. 


4.3.2 Physical I/O Operations 


There are four operations supported by the GPIO microcode to perform the physical I/O 
functions. These operations provide for (1) doing a name lookup, (2) doing a physical 
read of PS 300 mass memory, (3) doing a physical write to PS 300 mass memory, and/or 
(4) doing a synchronous physical write to PS 300 mass memory. The interface-specific 
commands and options for these operations are described in detail in the Customer 
Installation and User Manual for the appropriate interface. This section will describe the 
general data formats used in the physical I/O operations. 

• The first of these is the lookup format. The lookup requires a name, consisting of a 
string of characters and a 32-bit integer variable where the address of the named 
entity can be returned by the GPIO. Only one name can be looked up per QIO. If 
there isn’t an Alpha for the specified name, a null is returned for the address. 

• The physical read requires a special list of addresses to read from PS 300 mass 
memory. The addresses acquired through multiple lookupname calls are assembled 
into the addrlist. The format of this list is shown in Figure 4-1. When the physical 
read completes, it returns a list of addresses and data in the format shown in Figure 
4-2. 
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Reserved 

Number of blocks to read 
Block #1 source 
Block #1 word count 
Block #2 source address 
Block #2 word cotmt 


Block n source address 
Block n word count 


(used in Ethernet data 
transmissions) 
n <=255 

LS, MS Address of 
data read 
Number of 16-bit 
words read 


Figure 4-1. Format of Physical Read Address List 


- Reserved -— 

Number of blocks to read 

- Block #1 source address - 

Block #1 word cotmt 


Block #1 first data word 

• 


• 

Block #1 last data word 

— 

Block #2 source address - 

Block #2 word count 


Block #2 first data word 

• 


• 

Block #2 last data word 

— 

Block n source address - 

Block n word count 


Block n first data word 

• 


• 

Block n last data word 


n <=255 

LS, MS Address of 
data read 


Number of 16-bit 
words read 


Data returned after 
read 


Figure 4-2. Format of Data From PS 300 in Physical Read 
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• The physical write transfers a list of data to the PS 300 memory. The format for this 
list is shown in Figure 4-3. Note that the format is exactly the same as the data 
returned on a read. This allows you to do a physical read on a set of named entities, 
modify the data in the read list (do not modify the addresses), and write back the 
same list to the PS 300. 

• The physical I/O write synchronous operation ensures that each buffer gets at least 
one refresh before allowing the next write operation. It is possible to specify that the 
physical write operation be synchronized with the AGP clock. The format for the 
assembled data block in synchronous physical write is identical to physical write, 
shown below. 


- Reserved 

— 

Number of blocks to read 


- Block #1 source address 

— 

Block #1 word count 



Block #1 first data word 


• 

Block #1 last data word 
Block #2 source address 
Block #2 word count 

Block #2 first data word 

• 

• 

Block #2 last data word 
Block n source address 
Block n word count 
Block n first data word 


Block n last data word 


n<=255 

LS, MS Address of 
data read 
Number of 16-bit 
words read 

Data returned after 
read 


Figure 4-3. Format of Data to PS 300 in Physical Write 

4,4 Advanced Physical I/O Programming 

The Physical I/O process can produce distorted pictures when it is updating display 
structures at the same time the display processor is traversing them. To avoid this “single 
buffer” occurrence, these display structures can be “double buffered.” This is done by 
creating two copies of the named entities to be updated with different names (e.g. Datal 
and Data2). The data structures can then be alternately updated and displayed using 
either the IF LEVEL_OF_DETAIL or IF CONDITIONAL_BIT commands such as: 

TOP:=BEGIN_STRUCTURE 
LOD:=SET LEVEL OF DETAIL TO 1; 
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IF LEVEL = 1 THEN Datal; 
IF LEVEL = 2 THEN Data2; 
END_STRUCTURE; 


TOP;=BEGIN_STRUCTURE 
CB:=SET CONDrnONAL_BIT 1 ON; 
IF BIT 1 ON THEN Datal; 

IF BIT 1 OFF THEN Data2; 
END_STRUCTURE; 


These commands are used in conjimction with a node higher in the structured display file 
that either sets the level of detail (SET LEVEL) or sets the conditional bit (SET BIT). 

The node that performs the SET BIT and SET LEVEL operation is the Change Bits 
operation node. This operation node is also used to set displays, set character orientation, 
set contrast, set CSM, set depth clipping, set plotter, set rate external, set blinking, and 
set line textiore. The format and a more detailed description of this node is contained in 
Appendix J of this document. 

The SET LEVEL or SET BIT nodes can be updated using the physical I/O to “swap 
buffers.” Placing the update of the SET LEVEL or SET BIT structure last in the physical 
write list will ensure that the data are all correct before the buffers are swapped. 
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MODULE 5 

User-Written Functions Tutorial 


This module illustrates how to construct and use a simple user-written function (UWF). A 
user-written function is a Pascal procedure that will accept input data, process the data, and 
output the resulting data. User-written functions can be designed to perform operations not 
supplied by standard PS 300 functions and also to collapse large function networks into a single 
function. 


5.1 Introduction to User-Written Functions 



The User-Written Fimction facility is provided to allow you to expand and enhance the 
usefulness of your system by writing functions of your own design. User-written functions 
can be written to create new functions that perform operations not provided by intrinsic 
PS 300 functions. User-written functions may also be written to perform tasks that would 
require a large network of intrinsic functions to accomplish. For example, numerical 
calculations are usually easier to perform inside a single user-written function than within 
a function network. Substituting a single user-written function for a large network of 
intrinsic functions can be beneficial in two ways. First, programming a few functions in 
Pascal may be easier than programming a complicated function network. Second, due to 
the overhead incurred by scheduling each function in a large network, a single 
user-written function will usually take less execution time. When collapsing a large 
function network into a single user-written function, there are several considerations: 

- User-written functions execute somewhat more slowly than intrinsic functions. 
Therefore, collapsing a network consisting of just a few functions into a 
user-written function may not result in any improvement in performance. 

- It is usually not possible to replace an entire function network with a single 
user-written function. User-written functions tend to be more useful for 
performing specific tasks within the context of a larger network. Before writing a 
user-written function, you should be sure that the function has a well-defined 
purpose and a definite set of inputs and outputs. 


5.1.1 Requirements 



No separate hardware is needed to write your own functions. You must, however, be able 
to communicate with your host system. If your PS 300 is not equipped with terminal 
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5.1.1 Requirements 


No separate hardware is needed to write your own functions. You must, however, be able 
to communicate with your host system. If your PS 300 is not equipped with terminal 
emulator capabilities, you will need a separate terminal to communicate with your host 
and access host-resident utilities. 

To write your own functions, you will need the Motorola 68000 cross-software (compiler, 
assembler and linker). Before using the tutorial section of this manual, the Motorola 
software must be resident in your host system and available for use. 

The Motorola software may be purchased and licensed through E&S or from Motorola 
directly. The software available through E&S has been modified to run in DEC 
VAXA^S and VAX/UNIX environments; the software purchased from Motorola 
supports IBM (specifically MVS/TSO) environments. Further information on purchasing 
the software and the license can be obtained from your E&S Account Executive. 

You wiU also need two E&S-provided files, USERLINK.RO and USERSTRUC.PAS. 
These files are provided on magnetic tape and must be loaded on your host system before 
you can use the tutorial section of this manual. 

Command files that are provided for the tutorial section of this manual were written for 
the E&S-modified Motorola cross-software. Modifications to the files may be necessary 
if any other cross-software is used. 

These files are only provided for DEC VAX/VMS or DEC VAX/UNIX hosts. Users in an 
IBM environment should consult the appendices (C and D) for instructions and files that 
illustrate the use of the cross-software. 


5,1.2 Objectives 

In this module, you will learn: 

• The steps for constructing a sample function whose template should beused in writing 
user-written functions. 

• How to write your own function. 

• How to compile, link, and name the function. 

• How to transfer the function to the PS 300. 

• The restrictions on instancing the function. 

• How to use basic debugging techniques. 
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5.1.3 Prerequisites 

Before beginning this module, you should be familiar with the Pascal programming 
language, the use of PS 300 standard functions, and the downloading utilities on your 
host system. You should also make sure that your host system has the prerequisite 
Motorola compiler and linker software and that you have access to it. (IBM users should 
be familiar with the instructions in Appendix C of this manual.) You should have a 
PS 300 console and keyboard with terminal emulator capabilities, or a separate terminal 
that can communicate with your host system. Recommended books to have on hand that 
may be referred to are: 

- PS 300 Document Set, Volumes 1 through 5 

- Motorola Pascal User's Guide 

- Host-system utilities manual 


5.2 Constructing a Simple Function 

The first step in creating your own user-written function is writing the Pascal procedure 
that will later be compiled and transferred to the PS 300. The Pascal procedure must 
contain: 

- Calls to internal PS 300 functions and routines that allow your function to be 
scheduled and run 

- All the code necessary for your function to read data, process data, and write data 


Like all standard PS 300 functions, the function you write must wait until it has an input 
value on all queues, perform its computations,’ and then output the new values. All 
PS 300 functions must perform the same general series of actions when they are 
activated. These are: 

1. Fetch messages from the input queues. The function must have a message available 
on every queue before it can run. 

2. Make sure the messages received as inputs are of the appropriate type. If not, signal 
an error. 

3. Perform whatever calculations are necessary. 

4. Send output messages. 

5. “Clean up” the input queues and see if the function can be run again immediately. If 
so, go to Step 1. 

The following diagram and text illustrate a simplified version of the PS 300 function 
F:ADD and the Pascal procedure that supports it. 
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Function 


F:ADD 

I —<i> <i> 

I-*- <2> 


I 


Description 

F:ADD accepts integers as inputs and produces an output that is the sum of those 
integers. 


5.2.1 Example 


Note that the example contains comments. Some of these comments will be referred to 
in following portions of text. Refer to the Reference section of this manual for 
descriptions of the utility routines. This function, like all of the other examples included 
in this manual, was developed under DEC VAX/VMS. If you are using UNIX or an IBM 
system for developing your user-written functions, you may have to make minor changes 
in the examples. Refer to the appendix appropijate for your system for details on 
modifications and instructions on the use of the cross-software on your system. 


SUBPROGRAM UWFadd; 

{$F=USERSTRUC.PAS} 

PROCEDURE GenFunction; {procedure body must always be named GenFunction} 
VAR 

inputs ; PtrUWFInQarray; {pointer to data types in Qarray} 
outmsg : PtrUWFInQarray; {pointer to data types in Qarray} 


i : Integer; 

{ - } 

{ Main body of UWF } 

{ calls utility routine to check inputs for data, } 
{ checks inputs for valid data type, } 

{ returns error message if data are not valid. } 

{ - } 

BEGIN {GenFunction} 


inputs := Ckinputs (1, 2); {check for data on range of queues} 

WHILE inputs O NIL DO BEGIN 

IF inputstClJt-dtyp o Qinteger THEN {check for valid data type} 
QIllMessage (1) {error message if data are invalid} 

ELSE IF inputst[2]t.qtyp o Qinteger THEN {check for valid data type} 
QIllMessage (2) {error message if data are invalid} 


5-4 


PS 300 Advanced Programming 






User-Written Functions Tutorial 


ELSE BEGIN 

{ --- } 

{Allocate a new Qinteger to hold the output message. } 

(Then add the integers and send the sum from output <1>.} 

( - } 

outmsg := Newqinteger; (allocate memory block for output message} 
outmsgf.i := Inputs![1]t*i + Inputs![2]i; (put sum in output} 

{message} 

Sendmsg(outmsg,1); {send message to output <1>} 

END; 


{ - } 

{Call utility routine to flush queues and see if there is} 

{enough time to process more data; call Ckinputs to see } 

{if there is data on all queues. } 

(-j 

IF Cleaninputs THEN {flush input queues and see if there is enough} 

{time to process new data} 

inputs := Ckinputs(1,2) {check for data on queue <1> thru <2>} 
ELSE 


inputs := NIL {get out of WHILE loop} 
END; 

END 


From the example, you can see that the first requirement of the Pascal procedure is that it 
checks for inputs on both queues: 


inputs:=CkInputs(l,2); {Check for inputs on queues 1 through 2} 

This will hold true for any user-written function; nothing can happen until the function 
has data on all input queues. The queues are checked for input by Ckinputs, a utility 
function that accepts the range of the queues as parameters; for example, if the function 
had six queues, that line of code would read: 

inputs:=CkInputs(l,6); {Check for inputs on queues 1 through 6} 

Ckinputs has a pointer to each of the input queues specified in the inclusive range and 
stores them. When Ckinputs is called, if there are data on all of the queues, it will return 
with a pointer to the array. Ckinputs will return a NIL if there are queues in the range 
that do not have input. Notice that if NIL is returned, the F:ADD function will exit. In 
F:ADD, if there are data on both queues, the program can proceed. The procedure next 
checks to see if the data on input <1> are the specified data type: 


IF inputs![1]!.Qtyp o Qinteger THEN {input on <1> must be integer} 
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In this simplified version of F:ADD, the only acceptable data type is an integer. If the 
data type is not an integer, an error message is triggered, and the function cannot run. 
The utility routine, Qillmessage, would print out the message: 


Message which function cannot handle. 


signifying that the data on the queue were not of the specified type. 

Input <2> is then checked for an acceptable data type and the same process is repeated. 
In any function, all input queues must be checked to see if the data on the queues are the 
specified data type. Further, the specified data type must be one of the QData types 
defined in USERSTRUC.PAS. (This list is provided in the reference section of this 
document.) 

If both inputs have data, and data are in the specified range, the function can run. In this 
case, the function processes the data by adding the two integers together to produce a 
sum. Note that before the integers are added, a memory block is allocated for the output 
message with the statement: 


outmsg := NewQinteger; 

Memory must always be allocated for the processed data that will be placed on the output 
queue (s) of the function. Again, the outmsg must be one of the QData types defined in 
USERSTRUC. PAS. After the memory is allocated and the integers are added together, 
the sum is then sent as an outmsg to output <1> of the function: 


outmsgf.i := inputsf[1]t•i + inputst[2]i; {put sum in output message} 
Sendmsg(outmsg,l); (send message to output <1>} 

Finally, the program flushes the input queues by calling the Cleaninputs function, which 
also checks to see if there is more time available to process more incoming data: 


IF Cleaninputs THEN {clean up input queues and see if there is} 

{enough time to process new data} 

The utility function Cleaninputs should be called after the input data have been processed 
and the outputs have been sent. This function “cleans up” the input queues and 
determines whether there is enough time for the function to run again immediately. 
Cleaninputs will return a FALSE if the function has been running for more than 2 
centiseconds. Then, the inputs are again checked for data by calling Ckinputs: 


inputs := Ckinputs(1,2) {check for data on queue <1> thru <2>} 
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If inputs = NIL, there is no more data on the input queues and the function exits. This is 
a very simple example and demonstrates the basic principle behind writing the Pascal 
procedures that will be used as functions in the PS 300 system. 

The utility routines (or functions) that this program calls, Ckinputs and Cleaninputs, are 
just two of the utility subprograms that will be used in writing your own functions. These 
routines and functions allow for scheduling and communication between functions. A 
complete list of the utility subprograms are in the reference section of this manual. Most 
of them will be described and demonstrated in this module and in the Advanced Ideas 
module. The utility routines and functions are declared in USERSTRUC.PAS, along with 
the QData types already mentioned. USERSTRUC.PAS must be compiled along with 
your user-written function by using the inclusion: 


{$F=USERSTRUC.PAS} 

immediately after the name of your program. (See example.) It is important to remember 
that the rules that apply to standard PS 300 functions also apply to any functions that you 
will write. The first important rule to remember is that: 

There must be a message available on all input queues before the function will be 
activated. 


5.2.2 About Messages and Queues 

The input and output messages received by the function must belong to one of the QData 
types declared in USERSTRUC.PAS. These message types include all of the types used 
by intrinsic PS 300 functions: integer, string. Boolean, real, vector, and matrix. In 
addition, it is possible for user-written functions to define additional message types; this 
will be discussed in more detail later on. 

By default, all of the input queues for a user-written function are initially active queues, 
although you may use the SETUP CNESS command to establish some of the queues as 
constant queues. Within the code for the body of the user-written function, however, 
both constant and active queues are treated identically. 

For your function to work properly, you must be careful to use messages correctly. 
Improper use of messages is by far the most common source of problems with 
user-written functions. Failure to observe the rules for proper use of messages will, at the 
very least, cause your function to behave unpredictably, and may cause the PS 300 to 
crash. 

Messages used by a user-written function are of two types: those that are “owned” by the 
function, and those that are not. The only messages that are owned by the function are 
those that were created explicitly by the function, using the Pascal NEW function or the 
supplied functions NewQxxx and MsgCopy. The input messages to a function are NOT 
owned by that function. You should treat the input messages as being “read-only.” 
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The most important rule for handling messages properly is that a function should never 
attempt to modify, send, or dispose of messages which it does not own. You must also 
make sure that all of the messages that are created by the function are sent to an output 
queue (using SendMsg), stored on the private queue, or otherwise disposed of (as via 
DropMessage) before the function exits. (After this is done, the message is no longer 
owned by your function.) If the function exits without disposing of all of its owned 
messages, it will “eat” stoxage and may cause the PS 300 to crash as a result of exhausting 
available memory. 

Some of the utility functions and procedures provided cause the values of the messages 
they take as arguments to become undefined (as QSendCopyMsg), or they set the pointer 
to the message to NIL (as SendMsg). You should be aware of these side-effects; refer to 
the Reference Section for complete descriptions of the utility functions and procedures. 

Messages are actually sent in the order that you make the calls to SendMsg, but not until 
the function has finished running. You should be careful to send messages in the correct 
order where necessary. For example, the outputs of the Bezier curve function in Module 
6 are intended to be connected to a vector list. Output <1>, which clears the vector list, 
must be sent before output <2>, which appends to the vector list; otherwise the vector list 
would always be empty! 


5.2.3 About Function States 


Ordinarily, you need not be concerned about function states or the valid actions that a 
function can perform in each state, as long as the functions you write follow the template 
used in the examples in this manual. This information is provided for completeness. 

A PS 300 function instance may be in one of several states at any given time. Transitions 
between the states are caused by the scheduler in the PS 300 system, or by calls to utility 
procedures when the function is running. 

A function instance is in state MSG_WAIT while it is waiting for messages to arrive on all 
input queues. When all input queues have messages, the scheduler changes the state to 
ACTIVE and puts the instance on the list of functions that are ready to be activated. 
When the main procedure of the function is called by the scheduler, the state is changed 
to RUNNING. 

The function instance must be in the state RUNNING when the utility procedure 
Ckinputs is called. If messages are not available on all input queues, Ckinputs returns 
NIL and the function state is changed back to MSG_WAIT. If there are messages on all 
inputs, the function state is set to MID_RUNNING. 

While the function instance is in state MID_RUNNING, it should process its inputs and 
send outputs. When this is complete, the utility procedure Cleaninputs must be called. 
This procedure can only be called from the MID_RUNNING state. 
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After disposing of the previous input messages, Cleaninputs first checks to see if there are 
messages available on all input queues. If there are queues without messages, the state is 
changed to MSG_WAIT. Otherwise, a check is made to see if the function has been 
running longer than two milliseconds; if it has, then the state is changed to ACTIVE. 
(This gives other functions a chance to run.) 


If the function has not been running longer that two milliseconds, its state is changed to 
RUNNING, allowing it to run again with the new set of input messages. The function may 
continue to execute as long as it is in the RUNNING or MID_RUNNING state. It must 
exit immediately if the state is changed to MSG_WAIT or ACTIVE. The following 
diagram illustrates the change of states in a function instance. 


Function States Diagram 
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In the next section, Writing Your Own Function, you will be asked to write the Pascal 
procedure for a specific function. Before you begin this section, make sure you are 
familiar with the types of messages that can be handled and with the utility routines. This 
information in found in the Reference Section of this manual. 
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5.3 Writing Your Own Function 

The diagram below illustrates the function that you will be writing in this section. 
Function 



Description 

F:CHCASE accepts ASCII character strings (qpacket data type) on input <1> and a 
Boolean value on input <2>. When input <2> is set to TRUE, the characters received 
on input <1> will be output as upper case. When input <2> is set to FALSE, the 
characters will be output as lower case. Output <1> takes the processed character 
string from input <1>. Output <2> sends out an integer that is the length of the string. 

To write this function you must: 

1. Name the program. 

2. Include USERSTRUC.PAS, 

3. Define the variables. 

4. Check the inputs for data. 

5. Check for the legitimate data types. 

6. Allocate memory for the output messages. 

7. Change case according to the value on input <2>. 

8. Send the processed string to output <1>. 

9. Send the count of the string to output <2>. 

10. Flush the queues. 

11. Check all queues for more data. 

Because you will be using this program for exercises in compiling, linking, and 
downloading, for consistency it is suggested that you name your program: 

SUBPROGRAM ChCase; 




5.3.1 Exercise 

Design and write the Pascal procedure for the function F:CHCASE, as previously 
described. 


5-10 


PS 300 Advanced Programming 




User-Written Functions Tutorial 



5.3.2 Feedback 


The procedure for F:CHCASE is provided as an example. Please check your exercise 
against it to make sure you have included all the necessary steps. You can design your 
program in any number of ways, so long as it performs the necessary steps in the correct 
order. 


SUBPROGRAM ChCase; 
{$F=USERSTRUC.PAS} 

PROCEDURE GenFunction; 

VAR 

inputs : PtrUWFInQarray; 
length : Integer; 
outmsg : Ptrqdata; 
j,k : Integer; 



{ - } 

{ Utility functions for uppercasing and lowercasing a character } 

(--—j 

FUNCTION uppercase (ch : Char): Char; 

BEGIN 

IF (ch >= "a") AND (ch <= 'z') THEN 
uppercase := chr (ORD(ch) - 32) 

ELSE 

uppercase := ch; 

END; 

FUNCTION lowercase (ch ; Char): Char; 

BEGIN 

IF (ch >= "A") AND (ch <= 'Z') THEN 
lowercase := chr (ORD(ch) + 32) 

ELSE lowercase := ch; 

END; 



{ - } 

{ Main body of UWF } 

( - } 


BEGIN { GenFunction } 

inputs := Ckinputs (1, 2); 

WHILE inputs O NIL DO BEGIN 
IF inputstCl]t-Q^yP <> QPacket THEN 
Qillmessage (1) 
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ELSE IF inputsf[2]t•Qtyp o QBoolean THEN 
Qillmessage (2) 

ELSE BEGIN 


( ------ } 

{ Allocate a new QPacket big enough to hold } 
{ a the string. Then fill in the value and } 
{ send the message from output <1>. } 

{ - } 


WITH inputstElJt DO 

length := P_lth - P_beg + 1; 
outmsg := NewQPacket (QPacket, length); 
j ;= outmsgt.P_beg; 

FOR k := inputs![1]t.P_beg TO inputs![1]f•P_lth DO BEGIN 
IF inputs![2]!.b THEN 

outmsg!.P_cnt[J] := uppercase (inputs![1]!•P_cnt[k]) 
ELSE 

outmsg!.P_cnt[K] := lowercase (inputs![1]!•P_cnt[k]); 
j := j + 1; 

END; 

SendMsg (outmsg, 1); 


(-J 

{ Send a message indicating the length of } 

{ the string on output <2>. } 

(---J 


outmsg := NewQInteger; 
outmsgf.i := length; 
SendMsg (outmsg, 2); 

END; 

IF Cleaninputs THEN 
inputs := Ckinputs (1, 2) 
ELSE 

inputs := NIL; 

END; 

END. { GenFunction } 
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5.4 Compiling, Linking, and Naming the Fimction 

The procedure you have just written must now be successfully compiled and linked. The 
processor in the PS\300 that executes functions is the Motorola M68000 microprocessor 
and your code must be compiled and linked by Motorola cross-software. 

The next section provides simple instructions on using the files provided on magnetic tape 
for DEC VAX/VMS and DEC VAX/UNIX systems. 

IBM VM/SP and IBM MVS/TSO users should briefly familiarize themselves with the 
information provided here, and then refer to the appropriate appendices (C and D, 
respectively) in this manual for further instructions on using the cross-software. IBM 
MVS/TSO users should consult the Motorola manuals supplied with the cross-software. 

The first four appendices of this manual provide further instructions for each 
environment. If you are not operating in one of these environments, you will have to 
tailor the command files to your system or write your own. 

The code for all files is provided in the final appendix of this manual. 

Before continuing with this tutorial, make sure the cross-software and the files have been 
loaded on your system and that you have access to them. 

Use the Motorola Pascal User*s Guide as a reference to interpret any error messages 
produced by the compiler when your function is compiled. 


5.4.1 Description of the Command Files for DEC VAX/VMS and UNIX 

The command files provided for the DEC systems combine four specific tasks: 

1. Compile your Pascal procedure with the Motorola cross-compiler. 

2. Link your Pascal procedure with the MAIN program, USERLINK, to yield an 
S-record file. The S-record file is the definition of the userwritten function in a form 
that the PS\300 expects and will accept. USERLINK calls a procedure, GenFunction, 
which is the name of the body of the function that you have written. (Refer to the 
examples.) 

3. Append a trailing semicolon, to the end of the S-record file. The semicolon must 
terminate any S-record file that is transferred to the PS\300. 

4. Name your function. Before the S-record file can be downloaded to the PS\300 and 
the function instanced, it must be named. A name “header” must be created that 
includes the number of inputs, the number of outputs, and the stack usage of the 
function. (The stack usage is the number of bytes that must be reserved on the stack 
for the function and includes the count of all utility routines that the function uses. 
The reference section of this manual contains a listing of the stack usage for all the 
utility routines.) 
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When the command file is called, it accepts as arguments the function name, number of 
inputs, number of outputs, and stack size. 

There are several restrictions on the files thatare provided as an aid in compiling, 
cross-linking and finally naming your function: 

• The name of the file that will be compiled and linked using thecommand files 
must have the same name as the function. 


• The provided command file will only accept one file name. This means that 
functions that use several files must be compiled, linked, and named under a 
modified version of the command file. 


5.4.2 DEC VAXA^MS Command File 

Before executing the following command, you should: 

1. Set your default directory to the directory containing the source files for the function 
you want to compile and link. This directory should also contain copies of 
USERSTRUC.PAS and USERLINK.RO. 

2. Edit your login.com file to contain an @XNAMES command. 


As a convenience, a command file, XL.COM has been provided to compile and link your 
function and to produce the S-record file that is ready to be downloaded to the PS 300. 
All of the code for the function must be in a single .PAS file and the name given to the 
function is assumed to be the name of the file. To invoke this command, you should 
enter the command in the form: 

$ XL <filename> <number inputs> <number outputs> <stack size> 

In the above example, the brackets are provided to separate the arguments. When 
actually using the command, the brackets are not used and the arguments are separated 
by a single space. Error messages will be returned if any errors are encountered in the 
compiling, assembling, and linking process. 

When this message is displayed: 


<filename>.300 created 

the cross-software has been successfully called, an S-record file has been produced, and 
the name header has been created. This file, <filename>.300, is ready to download to 
the PS 300. 
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If functions that you may write later contain code from more than one file, or if you want 
to include routines you have written in assembly language, refer to Appendix A for 
instructions. Refer to the Motorola Pascal User's Guide to interpret error messages that 
are generated at the time your code is compiled. 


5.4.3 DEC VAX/UNIX Command Files 

Before attempting to use the cross-software, you should edit your .cshrc file to “source” 
the file xnames, which defines the necessary aliases and shell variables. This allows the 
assembler, compiler, and linker to be used as described in the EXORMACS manuals. 

Before executing the command described below, you should set your working directory to 
the directory containing the source files for the function you want to compile and link. 
This directory should also contain copies of userstruc.pas and userlink.ro. Since UNIX is 
case sensitive, remember to use consistent case for file names. 

As a convenience, a shell script xl has been provided to compile and link your 
user-written function and to produce the S-record file ready to be downloaded to the 
PS 300. Ail of the code for the function must be contained in a single .pas file, and the 
name of the function is assumed to be the name of the file. To invoke this shell script, 
you should enter the command in the form: 


% xl <filename> <number inputs> <number outputs> <stack size> 


In the above example, the brackets are provided to separate the arguments. When 
actually using the command, the brackets are not used and the arguments are separated 
by a single space. Error messages will be returned if any errors are encountered in the 
compiling, assembling, and linking process. Refer to the Motorola Pascal User's Guide 
to interpret these error messages. 

When this message is displayed: 


<filename>.300 created 


the cross-software has been successfully called, an S-record file has been produced, and 
the name header has been created. This file, <filename>.300, is ready to download to 
the PS 300. If functions that you may write later contain code from more than one file, or 
if you want to include routines you have written in assembly language, refer to Appendix 
B for instructions. 
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5.4.4 Instructions for IBM Systems 

If you are using an IBM system, refer to the following appendices (or manuals) for 
instructions. 

IBM VM/SP Appendix C for the names of the files appropriate for your 
system, information on the use of the cross-software on your 
host system, and example files that execute the 
cross-software. 

Appendix G for instructions on how to build the name 
header that will be downloaded to the PS 300 prior to the 
S-record file. 

IBM MVS/TSO Appendix D for the names of the files appropriate for your 
system. Please refer to the Motorola cross-software manuals 
for instructions on using the cross-software on your system. 
Appendix G for instructions on how to build the name 
header that will be downloaded to the PS 300 prior to the 
S-record file. 


5.4.5 Exercise 

Compile, link, and name the function FiChCase. If you are using the command files, 
remember that the name of the function must be the same as the name of the file that 
contains the Pascal procedure; i.e., your file name should be ChCase.pas. To successfully 
complete this exercise, complete the steps listed for your operating environment. 


For DEC VAX/VMS or UNIX: 

1. Invoke the command file appropriate for your host system. 

2. Enter the parameters for the function, FiCHCASE, including name, number of 
inputs, number of outputs, and stack size. (1000 is a reasonable estimate for the 
stack size of any function similar in size to F:CHCASE.) 


For IBM VM/SP: 

1. Compile and link your function using the instructions provided in Appendix C. 

2. Build the function header line (refer to Appendix F). 

3. Append your file with the trailing semicolon 
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For IBM MVS/TSO: 

1. "Compile and link your function using the instructions provided in the Motorola 
manuals and Appendix D. 

2. Build the function header line (refer to Appendix F). 

3. Append your file with the trailing semicolon 


5.4.6 Feedback 


The following example is provided to illustrate what should have been entered at your 
host terminal to call the Motorola cross-software successfully and to create the name 
header for your function for DEC systems: 

VAX/VMS: 

$ XL CHCASE 2 2 1000 

VAX/UNIX: 

% xl ChCase 2 2 1000 


IBM systems users should use the example files provided in the appendices to check their 
exercise. 


5.5. Transferring the Function to the PS 300 

After your Pascal procedure has been compiled and linked with the main program 
USERLINK, the S-record file output by the linker must be modified to include a function 
header line and to terminate with a semicolon. If you have compiled and linked your 
function using the command files previously described, this will be done for you. See 
Appendix F for a description of the header line format. 

If you are using VAX/VMS, UNIX, or any other ASCJI system over an RS-232 
asynchronous line, the S-record file can be downloaded by including the routing bytes to 
access the appropriate channel. Input on this channel is sent to a PS 300 function that 
writes the new function into mass memory in the Graphics Control Processor. 

For IBM systems or high-speed lines, these channels are accessed by using the Utility 
Routines provided by the PS 300 Graphics Support Routines (GSRs), rather that using the 
ASCII routing bytes. Both transfer methods will be discussed in the following section. 
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5.5.1 Using Routing Bytes to Transfer the S-Record File 

If you are not familiar with the use of routing bytes in the PS 300, please refer to Volume 
5 of the PS 300 Document Set. In general, routing bytes are used to toggle between 
different communication channels in the PS 300 system. In downloading the S-record 
files for user-written functions, the channel which loads the functions to mass memory 
must be accessed. The routing bytes that open this channel are t\6, where fX is the field 
separator character (decimal 28) and 6 designates the channel for loading user-written 
functions into memory. 

Once the user-written functions have been transferred to the PS 300, you should change 
the channel back to the terminal emulator so that any error messages can be intercepted 
and displayed on the PS 300 screen. The routing bytes for the terminal emulator are 
t\>. 

The routing bytes and S-record file can be sent to the PS 300 in number of ways. The 
suggestions that follow outline some of the normal communication methods available 
between the PS 300 and an ASCII host system. 

1. A host-system command file can be built that uses standard host transfer commands 

to send the mass-memory routing bytes then the file containing the name 

header and S-record file, and finally the routing bytes that open the communication 
channel to the terminal emulator. 

2. Individual files containing the routing bytes can be built and then copied to the 
PS 300 by a command file. The file transfers the opening sequence of routing bytes, 
the S-record file, and finally the routing bytes to change the channel. 

3. The file containing the S-record file can be edited using host facilities and the routing 
bytes can be included at the top and at the end of the file. The file can then be sent 
to the PS 300. The routing bytes are stripped out once the file is passed to 
communication functions in the PS 300, so they would not be the final code that is 
used by the function when it is instanced. 

5.5.2 Using the Graphics Support Routines to Transfer the S-Record File 

For any non-ASCII system, it is recommended that the utility routines in the Graphics 
Support Routines (GSRs) be used to access data channels and transfer the S-record file. 
The GSRs are provided in both FORTRAN and Pascal. If you are not familiar with the 
GSRs, refer to Volume 3b of the PS 300 Document Set. 

The channel parameter 7 should be used with’the utility routine, PMUXG, to access the 
charnel to mass memory. It is recommended that the channel to the terminal emulator, 
15, be reconnected after the transfer is complete so that error messages will be displayed 
on the PS 300 screen. 

■ The following Pascal program illustrates how the GSRs can be used to transfer the 
S-record file from the host system to the PS 300. This example illustrates the use of the 
GSRs in an IBM VM/SP environment. 


5-18 


PS 300 Advanced Programming 



User-Written Functions Tutorial 




File: SRECSND PASCAL * 

Program SRecSnd (input,output,srecfile); 


CONST 

%INCLUDE PROCONST 


TYPE 


VAR 


%INCLUDE 

PROTYPES 

srecfile 

: Text; 

istr 

: String (256); 

crlfa 

: Packed array (.1..2.) of char; 

crlf 

: String(2); 

foINCLUDE 

PROEXTRN 


PROCEDURE err (errnum : integer); 
BEGIN 

writeln( ^got error: errnum ); 

END; 


BEGIN 

pattach('junk',err); 
reset( srecfile); 
crlfa (.1.) : CHAR (13); 
crlf := STR(crlfa); 
pmuxg(7,err); 

WHILE NOT EOF (srecfile) DO 
BEGIn 

readln (srecfile, istr); 
pputgx (istr,err); 
pputgx (crlf, err); 

END; 

writeln; 
pmuxg(15,err); 
pdetach(err); 

END. 


5.5.3 Exercise 



Using any of the previously described methods, transfer the file ChCase.300 (renamed 
after it was compiled and linked) from your host system to the PS 300. 
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5.5.4 Feedback 

The only way to check and see if your file transferred successfully is to try to instance the 
function. This is done by entering Command mode on the PS 300 (refer to Volume 1 of 
the FS 300 Document Set for entering the communication modes) and instancing the 
function using the standard PS 300 command: 

instance name := FrCHCASE; 

If no error message is returned, the function was successfully downloaded and now 
resides in mass memory in the PS 300. 

If the downloading process fails, the PS 300 may crash and require rebooting. After 
rebooting, attempt to download the file at least once more. If the PS 300 still crashes, 
check the following: 

1. The correct file name was used in the transferring process. 

2. The correct routing bytes or channel parameters were used. 

If you are compiling and linking using the command files provided, the information and 
format of the S-record file are valid. If you are not using the command files, check for 
the following: 

1. Correct syntax in the name header, including adequate stack size. 

2. Trailing semicolon at the end of the file. 

3. Correct routing bytes or channel parameters. 


5.6 Instancing the Function 

When the function has been successfully transferred to the PS 300, it is instanced using 
the standard PS 300 command: 


instance name := F:user-written function name; 

Once the function is resident in mass memory, there are several restrictions that apply to 
all user-written functions: 

1. Initializing the system with the global INIT; command, or using the INIT NAMES; 
command will destroy not only all instances of the function, but also the body of the 
function. The function would have to be again transferred down from the host system 
before it would be available for use on the PS 300. Functions can be protected from 
the INIT commands. The procedure for doing this is described in Module 7. 


5-20 


PS 300 Advanced Programming 



User-Written Functions Tutorial 


2. Naming anything with the same name given to a user-written function will cause the 
function to be replaced by the new entity of that name. In particular, note that the 
command 

ChCase := F:CHCASE; 

will destroy the code for the function F:CHCASE. 

With the exception of those restrictions, the user-written function will respond as any 
intrinsic function resident in the PS 300. 


5.7 Debugging User-Written Fimctions 

The debugging environment on the PS 300 is less powerful than that used for debugging 
programs on the host computer. There is no symbolic debugger, and no way to include 
“writeln” statements inside the function to examine intermediate results and trace its 
execution. The function you are debugging is very much like a black box: you can see 
what goes in and what comes out, but you cannot look inside it. 

The standard technique for debugging a user-written function is to instance it and 
connect all outputs to F:PRINT functions, and from there to the terminal emulator or 
LABELS or CHARACTERS structures. Then, you SEND messages to the input queues 
of the function and examine the results. If the user-written function does not behave as 
expected, it is possible to replace the code for the function (by recompiling and relinking 
on the host and downloading the new S-record file) without losing the function instance 
or connections to and from it. 

If the function does not produce any outputs at all, make sure that it is receiving messages 
on all of its input queues. Remember that all queues default to being active queues unless 
you use SETUP CNESS to make them constant queues. 

If the function is only sending some of the output messages you expect, look for bugs in 
the body of the functibh. Make sure that SendMsg is being used to send the messages to 
the appropriate output queues. 

When the values of the output messages are incorrect, it is sometimes useful to modify the 
function temporarily to have additional outputs for sending intermediate results. By 
examining these values, it is possible to isolate the source of the problem. Once the 
problem has been fixed, the extra outputs can be removed. 

There are two common problems that cause running a user-written function to crash the 
PS 300. If the PS 300 crashes immediately (as soon as the function is activated), it is 
probably because the stack size you specified when you created the S-record file is not 
big enough. Try increasing this value. (Use the Stack Usage list in the Reference section 
of this manual to help determine stack size. The stack requirements are given for all the 
provided utility routines.) 
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Another cause of an immediate crash is when the number of inputs specified in the name 
header line is not correct. 

If the crash occurs randomly after the function has been run, it is probably the result of 
trying to send or otherwise dispose of a message which is not owned by the user-written 
function. The crash occurs when the true owner of the message tries to access it. In this 
case, you should examine the code for the function for proper use of messages. The 
Reference section of this manual contains a list of common crash messages and their 
probable cause. 

Remember that while your function is running, nothing else will. If the PS 300 seems to 
“hang” when the function is activated (i.e., it does not respond to the keyboard or other 
devices), look for an infinite loop in the function. Problems with message ownership can 
sometimes cause an infinite loop if you are trying to use a message whose value has 
become undefined (as by using SendMsg or QSendCopyMsg) as the upper limit of a FOR 
loop. 

Another common problem is when the function “eats” memory. This is usually most 
noticeable after the function has been run many times. In this situation, examine the 
function closely to be sure that all of the messages it creates are being sent as outputs, or 
otherwise disposed of, before the function exits. 


5.7.1 Exercise 


Create an instance of F:CHCASE. Connect it to a network that will allow you to examine 
the contents of the messages that are sent out of the function to determine if it is working 
correctly. To do this you will have to: 

1. Create an instance of F:CHCASE. 

2. Create an instance of F:PRINT for each output of F:CHCASE. 

3. Create a label node that will accept and display the character string from F:PRINT. 

4. Create a network that will feed the messages from the output of FiCHCASE through 
the PRINT function to the label node. 

5. SEND messages to the input queues of F:CHCASE and examine the results. 


5.7.2 Feedback 

The strings displayed on the PS 300 screen should accurately reflect the case of the 
characters in the string, as determined by the Boolean value on input <2> of F:CHCASE. 
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5.8 Conclusion 

This completes the module 5, the User-Written Functions Tutorial. By this time, you 
should be able to construct, compile and link, download, and instance a simple function. 
Module 6, Examples of More Advanced Ideas, moves from a strictly tutorial-format to a 
format that demonstrates by examples some of the more advanced programming 
capabilities that can be used when writing your own functions. 

Module 7 provides instructions for transferring user-written functions to the PS 300 
Firmware diskettes, allowing them to load with the system, and PS 300 commands that 
protect user-written functions from global INITIALIZE commands. It also contains 
information on the use of the PS 300 Debugger. 
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More Advanced Ideas 


This module illustrates, through examples and text, how to write more complex functions. There 
are four major examples, each illustrating a different type of function. The functions illustrate the 
following concepts: 


F:MAG 

F:COUNT 

F:BEZIER 

F:SPIRO 


How to handle more than one Qdata type on the same input queue. 
How to use the SetXCness utility routine and private data queues. 
How to write a function with a variable number of input queues. 
How to make use of the user-defined QData type. 


Before proceeding with this module, you should be familiar with: 

• The concepts presented in Module 5. 

• The information provided in the reference section of this manual. 

Should you need further exercise in writing functions, it is recommended that you use this section 
in the following manner: 

1. Examine the initial introduction to each example and the description of the function. 

2. Using the reference section of this manual, write a procedure to support the described 
function. 

3. Check your code against the examples provided. ^ 

4. Compile, download, and instance the function. 

5. Try it out. 
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6A Example I - Handling Different Message Types on the Same Queue 

F:MAG 

The magnitude function, F:MAG, is an example of a function that can handle several 
types of messages on the same input queue. This function will calculate the absolute 
value, if the input message is of type integer or real, or the length, if the input is a 2D or 
3D vector. 

If a function has two or more inputs that can take different message types, it is often 
necessary to make additional checks to make sure that the received messages are 
compatible types. If this is not the case, there is a utility procedure, QIncompatMsgs, 
provided to signal the error. 

F:MAG illustrates how the body of a function that can accept different types of inputs 
usually takes the form of a single IF / ELSE IF / ELSE statement. Each IF clause tests 
for a valid combination of inputs, with the final ELSE clause being used to flag an error. 

Function 


I, R, 2D, 3D 


F:MAG 


< 1 > < 1 > 


I, R 




Description 

This function calculates the absolute value (if integer or real) or magnitude (if a 
vector) of the input received. ♦ 


Example 

SUBPROGRAM uwfmag; 
{$F=:USERSTRUC. PAS) 


PROCEDURE GenFunction; 

VAR 

inputs : PtrUWFInQarray; 
outmsg : Ptrqdata; 
temp : double; 
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BEGIN {GenFunc tion} 

inputs := Ckinputs (1, 1); 

WHILE inputs <> NIL DO BEGIN 

IF inputs^[1]t.Qtyp = QInteger THEN BEGIN {send absolute value} 
outmsg := NewQInteger; 
outmsgf.i := abs(inputsf[1]f.i); 

SendMsg (outmsg, 1); 

END 

ELSE IF inputs![Ijf.qtyp = QReal THEN BEGIN {send absolute value) 
outmsg := NewQReal; 
outmsgt.r := inputs![1] 

FpAbs (outmsg!.r); 

SendMsg (outmsg, 1); 

END 

ELSE IF inputs![l]!.qtyp = QVec2 THEN BEGIN {send sqrt (x*x + y+y)} 
outmsg := NewQReal; 

FCMultiply (inputs![l]!.v4[0], inputs![1]!.v4[0], outmsg!-r); 
FCMultiply (inputs![l]!.v4[l], inputs![1]!.v4[1], temp); 

FCAdd (outmsg!-r, temp, temp); 

FCSqroot (temp, outmsg!.r); 

SendMsg (outmsg, 1); 

END 

ELSE IF inputs![l]!.qtyp = QVec3 THEN BEGIN {send sqrt (x*x + y* y) 

{z*z)} 

outmsg := NewQReal; 

FCMultiply (inputs![1]!-v4[0], inputs![1]!-v4[0], outmsg!-r); 
FCMultiply (inputs![l]!.v4[l], inputs![1]!-v4[1], temp); 

FCAdd (outmsg!.r, temp, outmsg!.r); 

FCMultiply (inputs![l]!.v4[2], inputs![1]!-v4[2], temp); 

FCAdd (outmsg!.r, temp, temp); 

FCSqroot (temp, outmsg!.r); 

SendMsg (outmsg, 1); 

END 

ELSE {anything else is illegal) 

QlilMessage (1); 

IF Cleaninputs THEN 
inputs := Ckinputs (1, 1) 

ELSE inputs := NIL; 

END; 

END. {GenFunction) 
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6.2 Example II - SET_CNESS and Private Queues 

F:COUNT The function F:COUNT is a simple counter function. Input <1> is the trigger 
queue. A Boolean value of TRUE causes the counter to be reset to the value received on 
input <2>. A value of FALSE causes the current value of the counter to be incremented. 
Input <2> is a constant queue. 

The utility procedure SetXCness is used here to “hard-code” the cness of the queues. 
Usually, it is preferable to rely on using the SETUP CNESS command to establish the 
cness of the queues for each individual instance of a function. If you use the SetXCness 
utility procedure, you cannot also use SETUP CNESS on the same queue. In F:COUNT, 
however, it is hard to imagine a situation where you would not want to have the initial 
value of the counter a constant queue, so you would want to use the SetXCness utility. 

If a function uses the SetXCness procedure, the call should appear at the very beginning 
of the function body. Trying to change the Cness of a queue back and forth in the middle 
of the function will probably not do anything useful. 

F: COUNT also illustrates the use of the private queue to store the current value of the 
counter. Ordinarily, a user-written function has no global variables or other permanent 
information that remain from one activation of the function to the next. Since being able 
to “save state” is sometimes required for a function to perform its proper task, each 
user-written function is provided with a private queue to contain permanent information. 

The name “private queue” is used because the only way messages can be placed there is 
from inside the function itself; you cannot SEND to the private queue of a function. 

When a function is instanced, the private queue is initially empty. Therefore, one of the 
very first things a function that uses the private queue should do is check to see whether 
or not there is already a message on the queue, using the utility function CkPrivate. This 
function will return a pointer to the message if it exists. If the queue is empty, create a 
new message of the appropriate type and use the function SavePrivate to store it in the 
private queue. Once a message has been saved on the private queue, it remains there 
permanently. The message is owned by the function and may be modified as necessary. 

Note that the private queue really is a queue, and may contain more than one message. 
You can chain several messages together into a linked list by storing a pointer in the 
NEXT field in the Qdata record. But be careful—messages on the private queue are the 
only instance where accessing the NEXT field directly will not cause huge amounts of 
trouble! 

In the case of FtCOUNT, the private queue contains a single message of type QInteger. 
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Function 




Description 

This function is a simple counter. The private queue is used to maintain the last value 
of the counter. 


F: COUNT 
< 1 > < 1 > 

<2>C 


Input <1> is the trigger queue. When a message of TRUE is received, the counter is 
reset to the value on input <2>. When a message of FALSE is received, the counter 
is incremented. The current value of the coimter is sent on output <1>. 




Example 

SUBPROGRAM uwfcouitt; 
{$F=USERSTRUC.PAS} 
PROCEDURE GenFunction; 

VAR 

inputs : PtrUWFInQarray; 
outmsg : Ptrqdata; 
status : Ptrqdata; 

BEGIN {GenFunc tion} 


{ - } 

{ Set input <2> to be a constant queue. This } 
{ is done because it does not make sense to } 

{ have this an active queue. } 

{ - } 

Set_Cness (2, TflUE); 

{ - } 

{ Get the inputs to the function and process. } 

{ - } 
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status := NIL; 

inputs := Ckinputs (1, 2); 

WHILE inputs <> NIL DO BEGIN 


{-} 

{ First the usual check for valid inputs. } 

{-j 


IF inputst [1] t-Q'tyP o QBoolean THEN 
Qillmessage (1) 

ELSE IF inputst[2]-t.qtyp o Qlnteger THEN 
Qillmessage (2) 

ELSE BEGIN 

{-} 

{ Now that^s taken care of, you need to get } 

{ the message from the private queue before } 
{ you can continue. If the private queue } 

{ is empty, allocate and initialize a new } 

{ message. } 

( --- } 

IF^Status = NIL THEN BEGIN 
status := CkPrivate; 

IF status = NIL THEN BEGIN 
status := NewQInteger; 

SavePrivate (status); 
statusf.i :=inputst[2]t.i; 

END; 

END; 


{-j 

^ { Then you can use the message from the } 

{ private queue to determine the value to } 
{ be output. } 

(-j 

IF^inputst[l]t-b THEN 

statusf.i := inputsf[2]f.i 
ELSE 

statusf.i := statusf.i + 1 ; 
outmsg := NewQInteger; 

outmsgt-i := statusf.i; SendMsg (outmsg, 1); 

END; 
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IF Cleaninputs THEN 

inputs := ckinputs (1, 2) 

ELSE 

inputs := NIL; 

END; 

END. { GenFunction } 


6.3 Example III - Variable Number of Input Queues 

F:BEZIER(N) 

The Bezier curve function, F:BEZIER(N), is an example of a user-written function which 
has a variable number of inputs. Input <1> is an integer indicating how many points on 
the curve are to be calculated. Inputs <2> through <N> are points (3D vectors) which 
define the Bezier curve. Output <1> of the function is intended to be connected to the 
<clear> input of a vector list, and output <2> should be connected to the <append> input 
of the same vector list. 

The body of the Bezier function is very similar to the code for any ordinary user-written 
function. The only difference is that, since you do not know how many inputs the 
instance of the function has ahead of time, you must call the utility procedure My\In\Out 
to find out. The call to this procedure should be placed at the very beginning of the 
function, before any calls to SetXCness, and before the initial call to Ckinputs. 

To indicate that a function has a variable number of inputs and/or outputs, you should 
specify the corresponding parameter as 255 in the header line of the S-record file. For 
example, since the Bezier function has a variable number of inputs and only 2 outputs, 
the header line should indicate 255 inputs and 2 outputs. On VAX/VMS, the command 
to compile and link the Bezier function is: 

4 

$ XL Bezier 255 2 5000 


Then, when you instance the function, you must specify the actual value for N, as 

<instance\name> := F:<function\name>(N); 

In this example, the following command will create an instance of the FrBEZIER function 
with 10 inputs: ^ 


drawit := F:Bezier(10); 
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If the function has a variable number of inputs, N specifies the number of inputs. If the 
function has a variable number of outputs, N specifies the number of outputs. If both the 
number of inputs and the number of outputs are variable, the function will have N inputs 
and N outputs. 

Another interesting point about the Bezier function is that it is very important to send the 
output messages in the correct order. Since the messages are actually delivered in the 
same order that they were sent within the function code, you must be careful that the 
clear message is sent on output <1> before any vectors are sent on output <2>. 
Otherwise, the vector list which, receives these messages would always appear empty. 

Function 


I 

3D 

3D 


F:BEZIER(N) 


<1> 

<1> 

<2> 

<2> 

• 


• 


• 


<N> 



—► to <clear> vector__list 
—► to <append> vector_list 


Description 


F:BEZIER evaluates a series of points on a Bezier curve. Input <1> is an integer 
indicating how many points on the curve are to be calculated. Inputs <2> through 
<N> are points (3D vectors) which define the vertices of the Bezier curve. Output 
<1> of the function is intended to be connected to the <clear> input of a vector list, 
and output <2> should be connected to the <append> input of the same vector list. 


Example 

SUBROGRAM uwfbezier; 
{$F=USERSTRUC.PAS} 


PROCEDURE Genfunction; 

0 

TYPE 

varray = ARRAY[1..MaxInputQueues] OF vector; 
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ins, outs 

Intl6; 

inputs 

PtrUWFInQarray; 

i, j 

Integer; 

npnts 

Integer; 

outmsg 

Ptrqdata; 

error 

Boolean; 

vertices 

Varray; 

t, delta 

Double; 


r> 


^ - , 

{ A function to evaluate the coordinates of a point on } 
{ a Bezier curve defined by ’’vertices" at parameter } 
{ value "t" } 

( - } 


FUNCTION eval_Bezier (VAR vertices : Varray; 

nvert: Integer; 
t: Double): vector; 

VAR 

j, k, m : Integer; 
temp : Double; 

BEGIN 

FOR j := nvert-1 DOWNTO 1 DO { loop over iterations } 
FOR k :* 1 TO j DO { loop over each vertex } 

FOR m := 0 TO 2 DO BEGIN { loop over x,y,z } 

FCSubtract (vertices[k+l,m], vertices[k,m], temp); 
FCMultiply (temp, t, temp); 

FCAdd (vertices[k,m], temp, vertices[k,m]); 

END; 

eval__Bezier := vertices[l]; 

END; 


{ - } 

{ Main body of UWF } 

{ --- } 


BEGIN { GenFunction } 

My_in_out (ins, outs); 
inputs := Ckinputs (1, ins); 

WHILE inputs O NIL DO BEGIN 
error := FALSE; 

IF inputs![llt-qtyp o QInteger THEN BEGIN 
error := TRUE; 

Qillmessage (1); 

END 
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ELSE IF inputs"[l]".i < 1 THEN BEGIN 
error := TRUE; 

Qillvalue (1); 

END; 

FOR i := 2 TO ins DO 

IF inputst[i]t-«ltyp O QVecS THEN BEGIN 
error := TRUE; 

Qillmessage (i); 

END; 

IF (inputs O NIL) AND (NOT error) THEN BEGIN 


{ - } 

{ Send the CLEAR message out first. You need } 

{ to save the value of input 1 before doing } 

{ QSendCopyMsg, because once this is done the } 
{ function no longer owns that message. } 

(-j 

npnts := inputsfCl]f.i - 1; 

QSendCopyMsg (1, 1); 

{-j 

{ Now calculate points on the curve and send } 
{ them on output 2. } 

{ - 


FCInt2Double (npnts, delta); 

FOR j := 0 TO npnts DO BEGIN 
FOR i := 2 TO ins DO 

vertices[i-1] := inputst[i]t-v4; 

FCInt2Double (j, t); 

FCDivide (t, delta, t); 
outmsg := NewQVector (QVecS); 

outmsgf.v4 := eval_Bezier (vertices, ins-1, t); 
SendMsg (outmsg, 2); 

END; 

END; 

IF Cleaninputs THEN 

inputs := ckinputs (1, ins) 

ELSE 

inputs := NIL; 

END; 

END. { GenFunction } 


<j 
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6.4 Example IV - User-Defined Qdata Type 

FrSPIRO 

F:SPIRO is a function which behaves like a spirograph toy. A spirograph consists of two 
gears, an inner wheel and an outer ring. A pen fixed to the inner gear traces a pattern as 
it is rotated inside the outer ring. 

Input <1> of the function will accept any message; it serves to trigger the function. The 
remaining inputs are constant queues. Input <2> is an integer specifying the number of 
teeth on the inner wheel, and input <3> specifies the number of teeth on the outer ring. 
Input <4> is a real number indicating the offset of the pen from the edge of the inner 
wheel. 

Output <1> is intended to be connected to the <clear> input of a vector list, and output 
<2> to the <append> input of the same vector list. A Boolean TRUE is sent on output 
<3> to indicate that there are additional points on the curve to be calculated. Output <4> 
is a boolean TRUE that is sent only when all points on the curve have been calculated. 

Instead of calculating all of the points which define the curve at once (as the F:BEZIER 
function does), FrSPIRO will only output one point each time it is activated. The state 
information is saved on the private queue so that the next time the function is activated, it 
can pick up where it left off. Output <3> can be connected back to input <1> to 
“reschedule” the function. 

This approach is useful because it allows the computations to be “interruptible.” If the 
spirograph function were allowed to run continuously until the entire curve was 
calculated, it could take up to several minutes to complete (depending on the complexity 
of the curve). During this time, nothing else would be able to run on the PS 300. 
Breaking up the computation allows other PS 300 functions to run normally—including 
updating of the vector list to which the spirograph function is connected. 

A special message type was defined to save the state information on the private queue for 
the spirograph function. One of the Qdata types, QuserType, is reserved for this purpose. 
A copy of USERSTRUC.PAS was modified to include a definition of the record type 
StateType, which contains fields to store the information that must be saved from one 
activation pf the function to the next. The declaration of the Qdata record type was then 
modified so that QuserType messages contain a field (Stateinfo) of this type. The 
spirograph function can then use the Pascal procedure NEW to create new QuserType 
messages. 


The foUowing is an excerpt from SPSTRUC.PAS (modified USERSTRUC.PAS) 
illustrating the definition of QuserType messages. 
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TYPE 


statetype = RECORD 
newdata 
maxi, maxo 
currenti, currento 
offset 

radiusl, radius2 
dthetai, dthetao 
END; 


Boolean; 

Integer; 

Integer; 

Double; 

Double; 

Integer 


{ next message in 
{ type of message 


a list of messages } 

} 


Qdata = 

RECORD 

Next: Ptrqdata; 

CASE Qtyp: Qdtype OF 




QuserType: 

( Stateinfo : StateType ); 
END ; { Qdata } 


You can also use QuserType messages for communication between a set of user-written 
* functions. These messages can be sent as output and received as input, just like any other 
message types. QuserType messages will also be handled correctly by any other function 
which accepts “any” message on the appropriate input, such as F:SYNC. 


Your function is responsible for correctly initializing QuserType messages. If the message 
type is to be shared by several functions, it might be convenient to add a procedure to the 
modified copy of USERSTRUC.PAS which creates and initializes new QuserType 
messages, similar to the predefined NewQxxx utility procedures. 


Qusertype Qtyp fields must be explicitly filled in by your program. Also, if the QuserType 
you define has fields in it that are pointers to other blocks, your_function is responsible 
for disposing of these blocks. They must be disposed of before disposing of the 
QuserType message. The DropMessage utility routine (used to dispose of messages) 
should be called after you dispose of any such blocks. 
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If your QuserType message is sent to a PS 300 intrinsic function that accepts “any” 
message on an input, any block pointed to in the internal fields of the QuserType will not 
be properly disposed of. If you must include pointers in your QuserType definition, make 
sure they are properly handled. 

Function 




F:SPIRO 


ANY 

(trigger) 

<1> 

<1> 

—► <clear> vector_list 

(inner circ.) 

<2>C 

<2> 

—► <append> Vector_list 

(outer circ.) 

<3>C 

<3> 

—► TRUE (continue) 

R -^ 

(pen offset) 

<4>C 

<4> 

—►TRUE (done) 


Description 

This UWF is a spirograph function. A spirograph consists of two circular gears, an 
inner wheel rotating inside a fixed outer ring. A pen is fixed to the inner gear at some 
offset from its circumference, so that it draws a pretty picture. 

Sending a message to input <1> triggers the function. Input <2> is the number of 
teeth on the inner gear, and input <3> is the number of teeth on the outer wheel. 
Input <4> is the distance the pen is offset from the circumference of the inner gear. 

The function outputs one line segment at a time. A value of TRUE is sent from 
output <3> to indicate that the function should be rescheduled. This output may be 
connected back to input <1>. TRUE is sent from output <4> when the curve is 
complete. 

The curve is constructed as follows. Maxi and maxo refer to the number of teeth on 
the inner and outer gears, respectively, and currenti and currento refer to the pair of 
teeth that are currently meshing. Dthetai and dthetao are the angles subtended by a 
single gear tooth on the inner and outer gears, respectively. Radius 1 is the distance 
from the center of the fixed ring to the center of the inner wheel, and radius2 is the 
distance from the center of the inner wheel to the pen. First, the angles of the two 
teeth that are currently meshing are found. The angles thetai and thetao are both 
relative to a fixed coordinate system. Then, the (x,y) coordinates of the pen location 
are given by: 

X = radiusl^cos(thetao) + radius2*cos(thetai) 
y = radiusl*sin(thetao) + radius2*sin(thetai) 

Note that the SinCos utility procedure expects the angle to be an integer from 0 to 
65536 (2*pi), so you use this format for all the angles throughout the function. 
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Example 

SUBPROGRAM uwfspiro; 

{$F==SPSTRUC.PAS } {USERSTRUC.PAS with Quserdata type defined} 

PROCEDURE GenFunction ; 

VAR 

inputs : PtrUWFUWFInQarray; 

outmsg : PtrQData; 

state : PtrQData; 

si, ci : Double; 

so, CO : Double; 

thetai : Integer; 

thetao : Integer; 


{ - } 

{ A utility procedure to fetch information } 
{ stored on the private queue. If nothing is } 
{ on the private queue, or if the information } 
{ is obsolete, reinitialize the state } 
{ information using the input msgs. } 
(-) 


PROCEDURE fetchestate_information; 

CONST 

pi2exp = 1027; { Exponent part of 2 * pi } 

pi2man = 1686628288; { Mantissa part of 2 * pi } 

VAR 

pi2, temp : Double; 

BEGIN 


{ - } 

{ If the private queue is empty, create } 

{ and store a new message. } 

{ - } 


state := CkPrivate; 

IF state = NIL THEN BEGIN 
NEW (State, QuserType); 
statef.Qtyp := QuserType; 
statet.stateinfo.newdata := TRUE; 
SavePrivate (state); 

END; 
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{-j 

{ If you are beginning a new curve, store } 

{ the new set of constants. Calculate } 

{ the radii of the two gears and find the } 

{ angle subtended by a single tooth, as } 

{ well as resetting other state variables. } 

{-} 

IF statef.stateinfo.newdata THEN 

statef.stateinfo.maxi := inputs![2]f.i; { copy input constants } 

state!.stateinfo.maxo := inputs![3]!.i; 

state!.stateinfo.offset := inputs![4]!.r; 

pi2.m := pi2man; { find gear radii } 

pi2.c := pi2exp; 

FCInt2Double (state!.stateinfo.maxi, temp); 

FCDivide (temp, pi2, state!.stateinfo.radius2); 

FCInt2Double (state!.stateinfo.maxo, temp); 

FCDivide (temp, pi2, state!.stateinfo.radiusl); 

FCSubtract (state!.stateinfo.radiusl, state!.stateinfo.radius2, 
state!.stateinfo.radiusl); 

FCSubtract (state!.stateinfo.radius2, state!.stateinfo.offset, 
state!.stateinfo.radius2); 

state!.stateinfo.dthetai := 65536 DIV maxi; { angles of one} 

{ gear tooth } 

state!.stateinfo.dthetao := 65536 DIV maxo; 

state!.stateinfo.currento := 0; { set current tooth counter } 

END; 

END; 


^-j 

{ Main body of UWF. } 

{-j 


BEGIN { GenFunction } 

{- 

{ Establish constant queues. 

{- 

Set_Cness (2, TRUE); 

Set_Cness (3, TRUE); 

Set_Cness (4, TRUE); 

{ - 

{ Check for valid inputs. 

{ - 

inputs := Ckinputs (1, 4); 

WHILE inputs o NIL DO BEGIN 

IF inputs![2]f.qtyp o Qlnteger THEN 


} 

} 

} 


} 

} 

} 
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Qillmessage (2) 

ELSE IF inputst[3]t.qtyp <> QInteger THEN 
Qillmessage (3) 

ELSE IF inputst[4]t.qtyp <> QReal THEN 
Qillmessage (4) 

ELSE IF inputst[2]t-i <= 0 THEN 
Qillvalue (2) 

ELSE IF inputst[3]t.i <= 0 THEN 
Qillvalue (3) 

ELSE IF inputst[2]t.i >= inputst[3]t.i THEN 
Qillvalue (2) 

ELSE BEGIN 


^- } 

{Get state info from the private queue. } 

{ - } 

Fetch_State_Information; 

{ --- } 

{ If you are starting a new figure, do } 

{ something special to initialize it. } 

{-i.-1—} 


IF statet.stateinfo.newdata THEN BEGIN 
outmsg := NewQInteger; 
outmsgt.i := statet.stateinfo.maxo; 

SendMsg (outmsg, 1); 
outmsg := NewQVector (Qvec2); 

FCAdd (statet.stateinfo.radiusl, statet.stateinfo.radius2, 


outmsgt-v4[0]); 

FCInt2Double (0, outmsgt.v4[1]); 

SendMsg (outmsg, 2); statet.stateinfo.newdata := FALSE; 
END; 

{ - } 

{ Calculate the next point on the figure. } 

{ - } 


statet.stateinfo.currenti := (statet.stateinfo.currenti+1) 
MOD statet.stateinfo.maxi; 

statet.stateinfo.currento := (statet-stateinfo.currento + 1) 
MOD statet.stateinfo.maxo; 
thetao := statet.stateinfo.currento * 
statet.stateinfo.dthetao; 
thetai := thetao - (statet.stateinfo.currenti ♦ 
statet.stateinfo.dthetai); 
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More Advanced Ideas 


Sincos (thetao, 

FCMultiply (so, 

FCMultiply (CO, 

Sincos (thetai, 

FCMultiply (si, 

FCMultiply (ci, 
outmsg := NewQVector (Qvec2); 
FCAdd (ci, CO, outmsgt.v4[0]); 
FCAdd (si, so, outmsgf.v4[1]); 
SendMsg (outmsg, 2); 


so, CO); 

statef.stateinfo.radiusl, 
statet.stateinfo.radiusl, 
si, ci); 

statef.stateinfo.radius2, 
statef.stateinfo.radius2, 


so) ; 

CO) ; 

si) ; 
ci) ; 


{ - } 

{ Test whether the figure is complete. } 

{ - } 

outmsg := NewQBoolean; 
outmsgt-b := TRUE; 

IF (statef.stateinfo.current! = 0) AND 

(state!-stateinfo.currento = 0) THEN BEGIN 


newdata := TRUE; 
SendMsg (outmsg, 4); 
END 
ELSE 

SendMsg (outmsg, 3); 

END; 

IF Cleaninputs THEN 

inputs := ckinputs (1, 4) 
ELSE inputs := NIL; 

END; 

El^. { GenFunction } 


6.5 CONCLUSION 


This concludes the formal instructions for writing your own user-written functions. On#e 
you are familiar with the processes and examples described in Module 5 and 6, the 
Reference section should be most helpful in providing a quick source of information on 
the utility routines, and other information you will need to write your own functions. 


Module 7 of this manual contains instructions for transferring S-record files from the host 
system to the PS 300 firmware diskette, as well as instructions for protecting user-written 
functions from PS 300 global INIT commands. Once user-written functions reside on the 
firmware diskette, they will load in approximately the same manner as intrinsic PS 300 
functions. Module 7 also contains instructions on how to use the PS 300 Debugger. 
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MODULE 7 


Loading and Debugging User-written Functions 


Section 7.1 of this module describes how to load a user-written function (UWF) from a runtime 
diskette (and optionally create an instance of the function) when the PS 300 is booted, in such a 
way that both the function code and the function instance are protected from INITIALIZE 
commands. For example, this facility might be used if you have written a function to control a 
peripheral device, such as a mouse, and you want to use the function in the same way as the 
ordinary PS 300 initial function instances. 

Section 7.2 of this module contains the various commands for the PS 300 Debugger and 
explanations of how to use them to determine whether a section of code for a user-written 
function is actually being executed or not. 


7.1 Loading User-Written Functions From Diskette 

Before proceeding with this section, you should know how to transfer files from the host 
computer to a diskette using the UTILITY program available on PS 300 Diagnostic Utility 
Diskette. You should be familiar with name suffixing conventions and how to use 
Configure mode on the PS 300. You may also find it useful to refer to the block diagrams 
for the CONFIG.DAT file. All of this information can be found in Volume 5 of the 
PS 300 Document Set. 

To load a user-written function from the firmware diskette, the file containing the 
user-written function must first be downloaded to the diskette from the host. This file 
should contain the function header line followed by the S-record output from the linker, 
and should terminate with a semicolon. It should not contain any multiplexing bytes. To 
download the file to the diskette, follow the instructions for using the UTILITY program 
in Volume 5 of the PS 300 Document Set. The file should be transferred as an ASCII 
file and given an extension of .DAT on the PS 300 diskette. 

Unless you are using a PS 300 with two disk drives, the procedures described in the 
following sections require that the file containing the function code be on the same 
diskette as the SITE.DAT file. 

To load the user-written function file on the diskette, you must modify the SITE.DAT file 
to include a function network which will read the file from the disk and route its contents 
to the function which will load the user-written function into memory. 
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If you want to instance the user-written function at boot time, you cannot just include the 
PS 300 commands to do so in SITE.DAT; this is because SITE.DAT is processed before 
the user-written function has been read in and loaded into memory. Instead, you must 
put the commands necessary to instance and initialize the user-written function in a 
separate file and modify SITE.DAT to include a network to read in this file after the 
user-written function code has been loaded. 

The function and its instances can be protected from INITIALIZE commands by creating 
them using a different Cl (command interpreter) than that used for commands received 
from the host or the keyboard. (Remember that an INITIALIZE command removes only 
those names which were created by the Cl receiving the command.) You will use the Cl 
numbered 0, which is also used for setting up the ordinary initial function instances from 
commands read from CONFIG.DAT. 


7.1.1 Loading the User-Written Function Into Mass Memory 


The following version of SITE.DAT sets up a function network which loads a user-written 
function from the file EXAMPLE.DAT into memory. After creating the file on the host, 
the PS 300 UTILITY program should be used to transfer it to the PS 300 diskette. 


configure sezme; dcwaitl := f:timeout; 
StartUWFl := fconstant; 

LoadUWFl := Lreaddisk; 
send fix(500) to <2>dcwaitl; 
conn dcwaitl<2> : <l>StartUWFl; 
send ’EXAMPLE’ to <2>StartUWFl; 
conn StartUWFl<l> : <l>LoadUWFl; 
conn LoadUWFl<l> : <l>srec__gather0; 
send fix(O) to <2>srec__gather0; 
disconn srec_gather0<l> : all; 
discorm srec_gather0<3> : all; 
send true to <l>dcwaitl; 
finish configuration; 


{ to force delay before reading UWF } 
{ holds name of file containing UWF } 
{ function to read the file } 
{ cause 5-second delay } 

{ then send filename to read function } 

{ route file contents to UWF loader } 
{ Cl number to associate with UWF } 
{ normally connected to a CIROUTE } 

{ kick the thing to get it started } 


This is the bare minimum required. Note that since the SITE.DAT file is read in 
Configure mode, you have to be sure to include the proper suffixes on all the names 
referenced. 

The function dcwaitl is used to force a 5-second delay between processing the 
SITE.DAT file and reading the file containing the user-written function. This delay is 
necessary because reading from the diskette disables interrupts which can fatally interfere 
with the data concentrator initialization sequence. This initialization takes place 
immediately after SITE.DAT has been read. To avoid conflicts, it is important to allow 
sufficient time for the initialization to complete before trying to read from the diskette. 
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After dcwaitl has been triggered and the delay time elapsed, it will send a message to 
input <1> of StartUWFl. In turn, this will send the name of the file to LoadUWFl, 
which reads the file from the diskette. The contents of the file are routed to 
srec_gatherO, an instance of F:GATHER_GENFCN. 

Sending a value of fix(O) to ^put <2> of srec__gatherO associates the name of all the 
user-written functions created by srec_gatherO with Cl number 0. This means that the 
names of these functions are protected from an INITIALIZE command on any other CL 
Note that this does not protect instances of these functions from INITIALIZE commands. 
Also, we must still be careful not to redefine the name of the function; i.e.. 


example := f:example; 


will still destroy the function body. 


7.1.2 Loading the User-Written Function and Creating an Instance 


If you want to create an instance of a user-written function at boot time, you should put 
the PS 300 commands necessary to do so in a separate file, which might be called 
SETUP.DAT. You can then modify SITE.DAT to include a network that reads 
SETUP.DAT from the diskette and sends its contents to the same Cl that processes the 
CONFIG.DAT and SITE.DAT files. The important thing to remember is that you cannot 
instance a user-written function until it has been loaded, so SETUP.DAT cannot be read 
in until the file containing the user-written function has been read in. 

There are a few restrictions on what SETUP.DAT can contain. First of all, the Cl used to 
process this file does not handle implicit name suffixing properly. You should always use 
Configure mode in SETUP.DAT, and be careful to include explicitly the proper suffixes 
on all names. Secondly, you cannot DISPLAY anything through this CL 

The contents of SETUP.DAT will vary depending on the application. Here is an 
example: 


configure sezme; # 

myexamplel := f:example 1; { whatever needs to be done to a initialize the } 

{ function } 

setup cness true <2>myexamplel; 
send true to <2>myexamplel; 

send ’System is ready for use’ & char(13) & char(10) to <l>es_tel; 
finish configuration; 

Note that, in Configure mode, you have to suffix the name of the user-written function, 
as well as any function instances that you refer to. 


PS 300 Advanced Programming 


7-3 



Loading and Debugging User-written Functions 


Once you have created the SETUP.DAT file on the host, use the PS 300 UTILITY 
program to transfer the file to the PS 300 diskette in the usual way. Unless you have a 
two-drive system, this file must be placed on the same diskette as the SITE.DAT file. 

Here is the SITE.DAT file to read the function code from EXAMPLE.DAT and the 
commands from SETUP.DAT. This network is illustrated in Diagram 2. 


configure sezme; dcwaitl := f:timeout; 
delayl := f:timeout; 

StartUWFl := fxonstant; 

LoadUWFl := Lreaddisk; 

StartSetupl := f:constant; 

LoadSetupl := Lreaddisk; 
send fix (500) to <2>dcwaitl; 
conn dcwaitl<2> : <l>StartUWFl; 
send ’EXAMPLE* to <2>StartUWFl; 
conn StartUWFl<l> : <l>LoadUWFl; 
conn LoadUWFl<l> : <l>srec_gather0; 
send fix(O) to <2>srec_gather0; 
disconn srec_gather0<l> : all; 
disconn srec_gather0<3> : all; 
conn LoadUWFl<2> : <l>delayl; 
send fix(lOO) to <2>delayl; 
conn delay 1<2> : <l>StartSetupl; 
send ’SETUP’ to <2>StartSetupl; 
conn StartSetupl<l> : <l>LoadSetupl; 
conn LoadSetupl<l> : <l>rfchop$; 
send true to <l>dcwaitl; 
finish configuration; 


{ to force delay before reading UWF } 
{ to delay before reading SETUP.DAT } 
{ holds name of file containing UWF } 
{ function to read the file } 


{ cause 5-second delay } 

{ then send filename to read function } 

{ route file contents to UWF loader } 
{ Cl number to associate with UWF } 
{ normally connected to a CIROUTE } 

{ trigger when UWF file is read } 
{ 1-second delay } 
{ then fire the function to read SETUP } 


{ to send it to the Cl } 
{ kick the thing to get it started } 


The first part of this network is the same as in the previous example. Output <2> of 
LoadUWFl is used to signal when the file containing the code for the user-written 
function has finished being read in. Use this message to trigger reading SETUP.DAT, 
after a one-second delay. (Experience has shown that this delay is necessary.) The 
contents of SETUP.DAT are routed to rfchopS. 


7.1.3 CONCLUSION 


The diagrams on the next page illustrate the function networks set up by the sample 
SITE.DAT files used in this module. 

This concludes the instructions for transferring S-records to the firmware diskette and 
initializing them at boot time. 
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Function Network Diagram 1 


dcwaitl 



F: CONSTANT F:READDISK 


Function Network Diagram 2 


dcwaitl 



F: CONSTANT F: READDISK 


delayl 



PS 300 Advanced Programming 


7-5 












Loading and Debugging User-written Functions 


7,2 PS 300 Debugger 

The PS 300 Debugger (Debug) can sometimes aid in debugging a user-written function. 
However, Debug is rather primitive and the procedure for locating the code for a user-written 
function in mass memory is complicated. It is suggested that you do not attempt to use Debug 
except when other methods for debugging a function have failed. You must be familiar with 
assembly language and the Motorola listing file formats to understand what is required to use 
Debug. This section describes: 

• How to use Debug. 

• The Debug commands. 

• How to set breakpoints in your user-written function. Setting breakpoints is useful for 
determining whether a section of code in your function is actually being executed or not. 

NOTE 

This discussion of the PS 300 Debugger has been updated to include 
modifications and additions that have been made to the Debug Eproms. 

For users whose systems do not have the new Debug proms the 
documentation in the User-Written Functions (E&S #901194-061) 
section of the PS 300 Docximent Set is still applicable. 


7.2.1 Using the Debugger 

To use the debugger, an ASCII terminal must be attached to PS 300 Port 3. The serial 
port used by Debug is initialized to 8 bits, no parity, and one stop bit; each byte is 
stripped to 7 bits in case the terminal being used sets a parity bit, and the baud rate is set 
to 9600. Should you want to modify these characteristics, you can do so by using the 
SETUP INTERFACE command for port30. 

Debug mode can be entered by pressing the BREAK key on the ASCII terminal. When 
Debug is entered, an asterisk “ * ” is displayed on the terminal and the PS 300 display is 
blanked. 

The asterisk is a prompt character that appears whenever Debug is expecting a command 
to be entered. All Debug commands are either one or two characters in length. Debug 
converts all lowercase characters to uppercase automatically. Whenever an invalid 
command is entered. Debug outputs a BEL and *'?” character, moves to the next line, 
and prompts for a new command. Refer to the next section in this module for tables 
containing the Debug commands. 

Because of its requirement to run on a minimum amount of hardware. Debug has several 
limitations. First, minimal editing of input is allowed. Second, all commands execute 
immediately upon pressing the appropriate key. Third, all numbers used by Debug must 
be hexadecimal (base 16) rather than decimal (base 10). 
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Any time a number is required by a Debug command, a 32-bit register is cleared to zero, 
and each digit that is entered into the register is shifted in from the right. If more than 
eight digits are entered, the upper digit is shifted out the left end of the register and lost. 
Numbers are considered completely entered when the first non-hexadecimal character is 
entered. (This implies that if the first character entered is not hexadecimal, the numeric 
value is zero.) 

Any time that a hex number may be entered, one of the following characters may be 
entered to provide a different meaning. Note that no additional delimiter character is 
required as with the entry of hexadecimal numbers. 

* Specify an ASCII string. The string is terminated by a second single quote. All 
characters are taken exactly as typed (no lower case to upper case conversion) 
including control characters such as carriage return and line feed (CTRL Y will 
still kill the command, however). Note that there is no way to insert a single 
quote character in this mode. This shoiild be most useful with the hunt 
commands (HB, HW, HL) or for inserting single characters into memory. 
Example: “I ’a’** would insert the value X’6r into the current open location. 


O Use the current open location as the hex value. Most useful with the list 
command (L) or to set breakpoints (BR). Example: “L O would list from the 
current open location for one line. 

P Use the current program counter value as the hex value. Most useful with the list 
command (L), to set breakpoints (BR), or with the open command (O). 
Example: “BR P” would set a break point at the current program counter 
location. 

S Use the current stack pointer value as the hex value. Most useful with the list 
command (L) or with the open command (O). Example: “OS” would open the 
location pointed to by the stack pointer. 

+ Use the current open location plus the specified offset. For example: “0+10.” 
would open the location 16 (X’lO’) bytes beyond the current open location (note 
that a delimiter is needed here). Or, “L +10, .” would list the line 16 bytes 
beyond the current open location. 

- Use the current open location minus the specified offset. For example: “O -A.” 
would open the location 10 (X’A’) bytes before the current open location (note 
that a delimiter is needed here). 
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When entering a hex number, you may now use either backspace or delete to correct the 
number. Up to the last 8 digits may be deleted from the number. A digit is deleted each 
time the delete or backspace key is pressed imtil the number being built is found to be all 
zero. Note that if more than 8 digits are entered, the first digits will have shifted out of 

the register and will no longer exist (but they will still appear on the screen). With this 

new feature, however, there should be no need to enter numbers longer than 8 digits in 
the first place. Note that backspace and delete do not work for any ASCII strings. 

Three special characters control output of data to the terminal: 

<CTRL>S Temporarily stops the sending of output to the terminal. 

<CTRL>Q Resumes the sending of output to the terminal after a <CTRL> S. 

(Note that program code occasionally may miss a 

<CTRL> S-<CTRL> Q sequence when displaying great amounts of 
data at a baud rate over 2400.) 

<CTRL>Y Permanently stops the sending of output to the terminal. <CTRL> Y 
may also be used to terminate any command before the last character 
of the command is entered. 



Any unrecognized character is echoed to the terminal but is otherwise ignored. Most 
valid commands move the cursor on the terminal to the next line to indicate successful 
completion of the command. 



7.2.2 Debugger Commands 

The following table lists the valid Debug commands. Most of the information in the tables 
is provided for completeness; only a few of these commands will be needed while using 
the debugger to set breakpoints in your code. The Debug program keeps a pointer to a 
specific location currently in use. This location is referred to as the “open Location”. All 
commands in the following table are associated with the open location. If a location has 
not been opened after a Reset or after stopping program execution using the O or Q 
commands, the current open location may be invalid and could cause a bus error if 
accessed. 


u 
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Table 7.2-1 Commands Accessing “Open” Memory Locations 


COMMAND 




DESCRIPTION 


O Open a location and display its contents. 

For example, to open location X’BA3E’: 

OBA3E. (Entered like this. Any delimiter can be used 

in place of the period in this and in the 
following examples.) 

* O BASE. (Displayed like this.) 

0000BA3E 00 * 

Q Open a location but do not display its contents. For example, to open location 

XTFF819*: 

QFFF819. (Entered like this.) 

♦Q FFF819. (Displayed like this. Note that the * cursor 

♦ moves to a new line but nothing else is 

displayed.) 


SPACE Insert a byte of data into the current open location and then open and display the 

contents of the next location. For example, if the current open location is X*BA3E' 
and the programmer desires to insert the bytes X’60* and X’FE* in this and the next 
location: 

_60._FE. (Entered like this. In this example, means 

space.) 

60. (Displayed like this.) 

0000BA3F 00 ♦ FE. 

0000BA40 00 ♦ 


(continued on next page) 
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Table 7.2-1 Commands Accessing “Open** Memory Locations (continued) 


COMMAND 


DESCRIPTION 


I Insert a byte of data into the current open location but do not move on to the next 

location and do not display the contents of any location. For example, if the current 
open location is X’FFF819* and the programmer desires to insert the value X’OO’ into 
the location: 

151. (Entered like this.) 

♦I 51. (Displayed like this.) 

♦ 

W Insert a word of data at the current open location. This command should be used 

when writing data to a register that is addressable on a word basis only. If the current 
open location is an odd address, the word is inserted into the next lower even address 
(to avoid an address error). For example, if the current open location is X’321FE’ 
and the operator wants to insert the word X*1234* into the location: 

W1234. (Entered like this.) 

*W 1234 (displayed like this.) 

♦ 

. Display the address and contents of the current open location. For example, if the 

current open location is X’FFF819': 

. (Entered like this.) 

*. (Displayed like this.) 

0FFF819 51 * 

Open the location after the current open location and display its contents. For 
example, if the current open location is X’BA3E*: 

+ (Entered like this.) 

*+ (Displayed like this.) 

0000BA3F FE ♦ 



/ Open the location after the current open location and display its contents. Identical 

to but does not require the use of the shift key. 

(continued on next page) 
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Table 7.2-1 Commands Accessing “Open” Memory Locations (continued) 


COMMAND 


DESCRIPTION 


Open the location before the current open location and display its contents. For 
example, if the current open location is X*BA3F’, this command would work as 
follows: 

(Entered like this.) 

(Displayed like this.) 

0000BA3E 60 * 


t 


The pointer following command. This command takes the 32-bit value at the open 
location and uses it as the new open location. Note that it does not check that the 
current open location is an even location (odd causes an address error), or that the 
value at the open location is a valid memory address (invalid causes a bus error). 
The following is an example of how to use this and other new commands to find the 
front of a diagnostic program and set a breakpoint at a subroutine listed as being at 
X’7DC* in the link map: 


R 

O 3A23E. 
O -A. 
t 

BR +7DC. 


Display registers (assume A5 = 3A23E). 

Open base of global variables. 

Get to diagnostic base address. 

Open the first location of the diagnostic. 

Set a breakpoint at the beginning of the subroutine. 


CTRL G Begin execution at the current open location. Do not set up any of the registers 

before beginning and do not enable breakpoints. This should normally be used to 
begin program execution when local memory may not be used to hold the exception 
vectors. Nothing is displayed by this command. 


PS 300 Advanced Programming 


7-11 



Loading and Debugging User-written Functions 


Table 7.2-2 Commands to List Data in Memory 


COMMAND 


DESCRIPTION 


L List a block of data in both hexadecimal representation and ASCII representation. All 
unprintable characters are displayed as a period. For example, to display locations 
X’40000* to X’4002F’: 

L40000,4002F. (Entered like this; period and comma are arbitrary delimiters.) 


(Displayed like this.) 
L40000, 4002F. 


00040000 

00 

01 

00 

00 

00 

04 

00 

14 

00 

01 

00 

00 

00 

04 

02 

DA 

.z 

00040010 

60 

00 

OA 

EC 

10 

38 

F8 

57 

11 

FC 

00 

4E 

F8 

55 

11 

FC 

. ..l.SxW...NxU.. 

00040020 

00 

7A 

F8 

55 

11 

FC 

00 

37 

F8 

F7 

11 

FC 

00 

41 

F8 

51 

.zxU...7xW...AxQ 


At this point, the current open location is set to X’40000’. For convenience, if the ending address 
is less than the starting address, the ending address is considered to be a byte-count. The list 
command accepts input in the form of: 

L<starting-address>,<number-of-bytes>. 
as well as: 

L<starting-address>,<ending-address>. 

For example, the following command could be used to display locations X’40000’ to X*4002F: 

L40000,2F. 

These addresses are obtained by a common routine which converts odd numbers to even numbers 
(so commands like ‘‘HW” do not get an address error). If an odd number is entered as the 
starting address, the first byte listed is actually the byte at the previous even address. 

> Display the line just after the last line displayed by the list (L) command. This is most 
useful when the block of memory listed was almost big enough but not quite. 

< Display the line just before the last line displayed by the list (L) command. This is most 
useful when one line of data was displayed (such as the current program counter location, 
and it is desired to see what was immediately in front of it. 
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Table 7.2-3 Program Execution and Debugging Commands 


COMMAND 


DESCRIPTION 


R Display contents of all processor registers at the time of the last exception. These 

contents are the values utilized by the “T” or “G” command. The values may be 
modified using the “A”, “D”, “P”, “S”, or “U” command. Most of these values 
are initialized to 0 by the “V” command. Registers are displayed in the following 
format: 

•R 

PC = 00000000 SR = 0000 USP = 00000000 

D0-D7= 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 

A0-A7= 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 

P Set the program counter to a new value. For example, to set the program counter 

to the value X’40014’: 

P40014. (Entered like this.) 

P 40014. (Displayed like this; note that the cursor moves 

to a new line but nothing else is displayed.) 

S Insert a new value into the status register. For example, to set the status register 

to the value X’2700’: 

S2700. (Entered like this.) 

S 2700. (Displayed like this; note that the cursor moves 

to a new line, but nothing else is displayed.) 

U Insert a new value into the user stack pointer (USP). For example to set the user 

stack pointer to the value X’36972’: 

U36972. (Entered like this.) 

U 36972. (Displayed like this; note that the cursor moves 

to a new line, but nothing else is displayed.) 


D0-D7 Change the value of the specified address register. For example, to set address 

register D2 to X’12345678’: 

D212345678. (Entered like this.) 

D2 12345678. (Displayed like this.) 

(continued on next page) 
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Table 7.2-3 Program Execution and Debugging Commands (continued) 


COMMAND 


DESCRIPTION 


A0-A7 Change the value of the specified address register. For example, to set address 

register A4 to X’FFFFF850’: 

A4FFFFF850. (Entered Uke this.) 

A4 FFFFF850. (Displayed like this.) 

G Begin program execution with all registers set up as displayed by the “R” 

command. Immediately before execution, all breakpoints are initialized in 
memory. If the first instruction to be executed is at a breakpoint address, several 
microseconds pass between the execution of the first instruction and any following 
instructions. If the program counter is odd, execution begins at the next lower 
even address. Nothing is output to the screen to indicate that the “G” command 
has been executed. 

T Trace one instruction. All registers are set up as displayed by the “R” command. 

This instruction uses the trace bit in the MC68000 microprocessor. Since 
breakpoints actually are only set up in memory when the “G” command is 
executed, they have no effect on the trace command. If the program counter is 
odd, execution begins at the next lower even address. After tracing one 
instruction, the following is displayed (with actual register values filled in): 

*T Trace PC= 00000000 SR = 0000 USP = 00000000 

D0-D7= 00000000 00000000 00000000 00000000 00000000 00000000 
00000000 00000000 

A0-A7= 00000000 00000000 00000000 00000000 00000000 00000000 
00000000 00000000 

V Initialize exception vectors, registers, stack pointer, and breakpoint table. Care should be 
taken not to type a “V” while debugging your program, as the machine state will be lost! 
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Table 7.2-4 Breakpoint-Related Commands 

Up to seven breakpoints may be set for Debug programs. Debug sets a breakpoint by storing a 
TRAP #15 instruction at the breakpoint location when the “G” command is executed. Every time 
an exception occurs that causes DEBUG to be entered (e.g. pressing the BREAK key or 
encountering a breakpoint), the ctirrent open location is set equal to the program counter 
address. This is especially useful when using the trace command or when using breakpoints. 


The programmer must assure that no attempt is made to set a breakpoint at a nonexistent 
location. If the breakpoint is set at an odd location, the next lower even address is used. It is 
important that the breakpoint be set at the beginning of an instruction rather than in the 
instruction parameter part. 


If there is not enough room to set another breakpoint. Debug indicates it is full with the following 
message: 


Break table is full 


COMMAND 


DESCRIPTION 


BR Set one breakpoint. A maximum of 7 breakpoints may be set up at any one 

time. If this number is exceeded, the following message is displayed: 

Break table is full 

For example, to set a breakpoint at location X’COOO': 

BRCOOO. (Entered like this.) 

*BR COOO, ’(Displayed like this.) 


BD Display all breakpoints. For example, if three breakpoints have been set, the 

following might be displayed: 

BD (Entered like this) 

Breakpoints = OOOOCOOO 0000CAB8 0000C124 (Displayed like this) 

If no breakpoints are set, the following message is displayed: 

Breakpoints = 


(continued on next page) 
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Table 7.2-4 Breakpoint-Related Commands (continued) 



COMMAND 


DESCRIPTION 


BC Clear one breakpoint. If the system is unable to clear the breakpoint for any 

reason, the cursor remains on the same line. If the breakpoint is successfully 
cleared, a carriage return is output to indicate successful completion. If the 
breakpoint is not successfully cleared, the audible alarm sounds. For example, to 
clear a breakpoint that was set at location X’COOO*: 

BCCOOO. (Entered like this.) 

BC COOO. (Displayed like this.) 


BA Remove all breakpoints. 
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Table 7.2-5 Hunt Commands 

The Hunt commands HW, HB, and HL are used to look for a word (16 bits), for a byte (8 bits), 
or for a long word (32 bits), respectively, in a search range designated by the programmer. 


COMMAND 


DESCRIPTION 


HW 


Hunt for a word (16 bit) pattern within a specified search range designated by the 
programmer: 

HW400,10000. (Entered like this.) 

HW 400, 10000. (Displayed Uke this.) 


NOTE 

If the specified search range is to be X’lOO* to X’lFF’, enter the number 
range 100 to 200. The ending address is the one immediately preceeding 
the address entered by the operator. 


A prompt then asks for the pattern to search for, and the programmer responds as in 
the following example: 

Pattern to search for: 4ED0 

Once a matching pattern is found, its address is displayed, along with the 16 bytes 
following the address, as in the following example: 

0000EB(J4 4E DO 00 00 00 00 00 00 00 00 00 00 00 00 00 00 . 

Pressing any key on the terminal continues the search for another matching pattern from 
the point after the last pattern found until the end of the range. A <CTRL> Y may be 
used to stop the search at any time. When no matching pattern is found, the following 
message is displayed: 

Not found 

If the pattern to search for is an ASCII sequence of characters, the characters must be 
surrounded by single quote marks. Note that if an entry is found within 16 bytes of an end 
address, the whole line is not printed to avoid a bus error in case the end address is on a memory 
boundary. 


‘HB Hunt for a byte (8 bit) pattern within a specified search range designated by the 

programmer. 

HL Himt for a long word (32 bit) pattern within a specified search range designated 

by the programmer. 
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Table 7.2-6 Boot-related Commands 


COMMAND 


DESCRIPTION 


NOTE 

The error-correction bits of memory must be initialized by either the 
confidence tests or a memory text (such as Ml) prior to execution of the 
boot-related commands. 

Should an error occur while executing one of the boot-related 
commands, additional error information may be obtained by reading the 
diskette controller status bits at location X‘FFF8ir. 


BO Load and execute the boot file from the minifloppy. This command must be 

followed immediately by a carriage return. 

A “V” command is automaticaUy executed immediately before accessing the 
diskette controller to guarantee that memory error correction logic is enabled and 
that the exception vectors are initialized. 

The floppy disk drive is turned off after the file is loaded into memory. Any code 
that uses the disk immediately after being loaded must explicitly turn the disk 
motor on again. 


NOTE 

All breakpoints disappear when the boot command is executed. 


If an error is encountered, one on of the following messages is displayed: 

Disk initialization error 

This error message indicates tha either the diskette drive does not respond 
properly or that there is no diskette in the drive: 

Error in locating boot file 

This error message indicates that either the diskette could not be read or that the 
diskette does not contain a valid boot file. 

Error in loading boot file 

This error message indicates that either a read or a seek error occured while 
reading in the boot file. 

(continued on next page) 
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Table 7.2-6 Boot-related Commands (continued) 


COMMAND 


DESCRIPTION 


BN Load the boot file in from the diskette but do not begin execution. This command 

is identical to the BO command except that when the file is loaded, instead of 
beginning execution immediately, control is returned to the programmer and the 
following message is displayed: 

Start address = XXXXXXXX 

where XXXXXXXX is the address where the program was loaded. This command 
must be followed immediately by a carriage return. 

Note that a “V” command is automatically executed immediately before accessing 
the diskette controller to guarantee that memory error correction logic is enabled 
and that the exception vectors are initialized. This means that all breakpoints 
disappear when the boot command is executed. 

The floppy disk drive is turned off after the file is loaded into memory. Any code 
that uses the disk immediately after being loaded must explicitly turn the disk 
motor on again. After the file is loaded, the start address is opened. A CTRL G 
command may be entered without explicitly opening the start address. 


BX Load the specified file from the diskette to the specified address. This command 

must be followed immediately by a carriage return. The file name is entered 
following the prompt message: 

Enter name of file: 

The name may be from 1 to 8 characters in length. Should an error be made in 
entering the file name, type a CTRL Y and begin again. 

No local memory accesses of any kind occur (unless the load address is within 
local memory). If any breakpoints are set at the time that the “BX” command is 
entered, the original instructions at the breakpoint locations may not be restored. 

NOTE 

• Debug does not allow the programmer to specify the extension or file 
. version number. The file must be of the type .EXS (executable 
stand-alone) to be loadable by the BX command. The highest version 
number of the file is loaded in automatically; there is no way to select an 
alternate version number. 

(continued on next page) 
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Table 7.2-6 Boot-related Commands (continued) 


COMMAND 


DESCRIPTION 


The load address is entered following the prompt message: 

Enter load address: 

If the address is odd, the next lower even address is used. This eliminates the 
possibility of an address error while executing the specified file. 

The floppy disk drive is turned off after the file is loaded into memory. Any code 
that uses the disk immediately after being loaded must explicitly turn the disk 
motor on again. After the file is loaded, the start address is opened. A CTRL G 
command may be entered without explicitly opening the start address. 
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Table 7.2-7 Memory Test Commands 


COMMAND 


DESCRIPTION 


NOTE 

Memory tests M3 through M6 strobe the DIAGSYNC line on the GCP 
card whenever a memory error is detected. This allows a logic analyzer 
to capture the state of the hardware at the time of the memory error. 


Ml 



Test the GCP local memory. This test starts at location X‘0008’ and tests all of 
local memory. It performs a stripes^pattern test of all bits for both Ts and O’s, 
coming from both directions. 

After all normal memory bits have been tested, the test above is repeated using 
the check bits. This test has no parameters. Errors are displayed in the 
following manner: 

00000100 Expected-5555 Received-5554 Bits in error-0001 

where the first field is the address where the error was detected, the second is the 
expected value, the third is the received value, and the founli contains the bits 
in error as determined by the test. 


M2 Test the error correction and detection circuitry of the local memory. 


M3 


• n 


Perform a simple and quick complement test. M3 reads a location, complements 
it, and then verifies that all bits have changed. For example, to test memory from 
X‘0008’ to X‘03FF’: 

M38,400. (Entered in this form.) 

M3 8, 400. (Displayed in this form.) 

Note that the last location tested is X‘3FE’ (word address), which includes 
location X‘3FF* (byte address). The end address corresponds to the first even 
address after the last address to be tested. A carriage return is output when the 
test is started, and another carriage return is output when the test has been 
completed successfully. Errors are displayed in the same way as in test Ml. 


(continued on next page) 
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Table 7.2-7 Memory Test Commands (continued) 


COMMAND 


DESCRIPTION 


NOTE 

For convenience, if the ending address is less than the starting address, 
the ending address is considered to be a byte-count. The M3 command 
accepts input in the form of: 

M3<starting-address>,<number-of-bytes>. 


as well as: 


M3<starting-address>,<ending-address>. 


For example, the following command could be used to test locations 
X‘200000* to X‘2001FE*: 

M3200000,200. (Enterd in this form) 

M3 200000, 200. (Displayed in this form) 

These addresses are obtained by a common routine which converts odd 
numbers to even numbers. This eliminates the possiblity of an address 
error. 


M4 Perform an address line test. It stores the low order 16 bits of the address at the 

test address and then, when all of memory to be tested has been filled, it verifies 
that the proper data has been stored. Addresses are specified the same way as 
in test M3. 


MA Execute the read and verify portion of the memory address lines test (M4). This 

command is intended to be preceded by an M4 test over the same range (and 
thus verifies that the data written by M4 is still intact). Following is an example 
of how it might be used: 

M4 200000, 210000. (Write the data pattern) 

<wait a while> 

MA 200000, 210000. (Verify data integrity) 


(continued on next page) 
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Table 7.2-7 Memory Test Commands (continued) 


COMMAND 


DESCRIPTION 


M5 Perform a simple stripes test. The test procedures are the same as those 

described in memory test command Ml above, except the operator specifies the 
test range and the MMMR (Mass Memory Maintenance Register) is not 
modified. 

M6 Store a random pattern throughout the test memory, using a pseudo-random- 

number generator. After all of memory has been filled, the seed of the random 
number generator is reset and then all memory locations are verified. Addresses 
are specified in the same way as with test M3. 




o 
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7.3 Setting Breakpoints in Your Code 

This section describes the steps you must follow to set a breakpoint in your code. Where 
appropriate, examples are given. The user-written function F:MAG will be used for the example. 
It is assumed that you want to put a breakpoint right after the function has checked its input 
queues upon being executed. 

1. Make sure that your compile, assemble and links are done with the List option set 
on. (Refer to the Motorola cross-software manual for more details on the List 
option.) This causes creation of listing and link-map files which are necessary to 
find the location to a set breakpoint. For F:MAG, the commands to do this on 
VAX/VMS are: 


$ xpas mag 
$ xpas2 mag;L 

$ xlink mag/userlink,mag,mag;himx 

2. Find the offset within the user-written function code of the breakpoint location using 
the listing file from pass 2 of the compiler and the link map. 

a. Find the address within the link of the beginning of the filecontaining your code. 
The link map will give you this information. In the following example, for F:MAG, 
the code for the user-written function (Module USERFUN) starts at location 2CC. 


Load Map: 


Segment SEGO: 00000000 OOOOOOFF 0,1,2,3,4,5,6,7 

Module S T Start End Externally Defined Symbols 


USERLINKl 00000000 00000019 

USERLINK6 OOOOOOIA 00000025 


Segment SEGl(R): 00000100 000005FF 8,9,10,11,12,13,14 
Module S T Start End Externally Defined Symbols 


USERLINK 8 

OOQOOIOO 00000173 

.PALSTS 

00000108 

.PDIS 

00000156 



.PLJSR 

00000100 

.PNEW 

0000012E 
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USERLINK 9 

00000174 

000002CB 

FRAMES 

0000027C 

SENDMSG 

0000018C 




SET__CNES 

000002C4 

SYSTEMER 

000001B6 




TEXT_TEX 

00000294 

UWFERROR 

000002BC 




HRTIME 

00000284 

QILLMESS 

00000198 




QILLVALU 

0000019E 

QINCOMPA 

000001A4 




FCADD 

000001C8 

FCDIVIDE 

000001F4 




FCINT2D0 

OOOOOIFA 

FCINTEGE 

00000206 




FCMULTIP 

000001D4 

FCNEARZE 

0000020C 




FCP2MULT 

OOOOOIEE 

FCROUND 

00000200 




FCSQROOT 

00000212 

FCSUBTRA 

OOOOOICE 




SINGOS 

00000218 

VFETCH 

0000024E 




TICKS 

0000026C 

TIME__TEX 

000002A4 




CHAR_TEX 

0000028C 

MSGCOPY 

OOOOOIAA 




RNDMNUMB 

0000021E 

CKINPUTS 

00000180 




CKPRIVAT 

00000174 

CLEANINP 

00000186 




QSENDCOP 

00000192 

MY__IN_OU 

00000264 




MY_NAME 

0000025C 

NEWQBOOL 

00000236 




NEWQINTE 

00000230 

NEWQMATR 

00000248 




NEWQNIL 

0000023C 

NEWQPACK 

00000224 




NEWQREAL 

0000022A 

NEWQVECT 

00000242 




NEWTRY 

000002B4 

SAVEPRIV 

0000017A 




CSECS 

00000274 

DROPMESS 

OOOOOIBO 




FPABS 

000001C2 

FPECOMP 

OOOOOIBC 




VSTORE 

00000254 

INT_TEXT 

0000029C 




REAL_TEX 

000002AC 



USERFUN 9 

000002CC 

0000057F 

GENFUNCT 

000002CC 




b. Find the offset within your file of the particular instruction you want to set the 
breakpoint at. The listing file from pass 2 of the compiler will give you this 
information. 
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In this example, the breakpoint will be set just after the initial call to Ckinputs. Here is 
the relevant part of the listing file: 



* 


PROCEDURE GenFunction ; 


3iC 

:fc 

* 


VAR 

inputs 

outmsg 

temp 


PtrUWFInQarray; 

Ptrqdata; 

Double; 




BEGIN { GenFunction } 

inputs := Ckinputs (1, 1); 


00000000 



USERS0 EQU * 

00000000 

2F2D 

OOOC 

MOVE.L 12(A5),-(A7) 

00000004 

4E56 

FFFF 

LINK A6,#-Ll 

00000008 

2B4E 

OOOC 

MOVE.L A6,12(A5) 

oooooooc 

598F 


SUB.L #4,A7 

OOOOOOOE 

7001 


MOVE.L #1,D0 

00000010 

3F00 


MOVE D0,-(A7) 

00000012 

7001 


MOVE.L #1,D0 

00000014 

3F00 


MOVE D0,-(A7) 

00000016 

4E93 


JSR (A3) CUP 

00000018 



DC.L $00FFFFE8 

OOOOOOIC 

2D5F 

FFFC 

MOVE.L (A7)+,-4(A6) 

*. WHILE : 

inputs o 

NIL DO BEGIN 

00000020 



L2 EQU * 

00000020 

206E 

FFFC 

MOVE.L -4(A6),A0 — 

00000024 

227C 

00000000 

MOVE.L #0,A1 

0000002A 

B1C9 


CMP.L A1,A0 

0000002C 

6700 

0000 

BEQ L3 


326 

327 

328 

329 

330 

331 

332 

333 

334 


335 

•>(see note) 



NOTE 

The location where you should set the breakpoint is offset 0020 from the 
beginning of the module. 

c. Add the two numbers arrived at in (a) and (b). This will give you the actual offset 
from the beginning of the user-written function of the instruction at which to set 
the breakpoint. In this example, the actual offset is 2CC + 20 = 2EC. (Remember, 
all numbers are Hex.) 


W 
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3. Find the address in PS 300 mass memory of the start of the function code. After 
downloading the user-written function so that it is in place in the PS 300 mass 
memory, enter Debug by depressing the Break key on the ASCII terminal connected 
to port 3. Look through mass memory (using the HL or HW command) for the name 
of the function. Use the first 4 characters of the name only. Remember that all 
names have a suffix appended to the end of the name. For most functions 
downloaded from the host the suffix is a “ 1” (one). Hunt through memory starting at 
location 200000 and ending at 300000 (or 400000, if you have 2 megabytes of mass 
memory, 500000, if you have 3 megabytes, etc). The example function is named 
MAG. Thus you should hunt for the characters “MAGI”. Enter the following 
commands to the debugger: 

♦ HL 200000 300000 

Pattern: ’MAGI* { use CAPITAL letters only } 

When the debugger finds the first place in memory that this name exists it will display the 
line and address containing this name. Hit RETURN to have it search for the next one. 
Continue until the debugger returns with the message: 

Not found 

The name may actually exist in several places in mass memory, although only one of these 
locations will help you find the function code. If the name exists more than once, you 
must decide which is the “right one.” The address given at the beginning of the line must 
end with an “E.” This may help to eliminate some locations. 

In the example the terminal looked like this after searching through memory: 

00225332 4D 41 47 31 00 00 00 00 00 00 00 00 00 00 00 00 MAGI.. . 

0022928E 4D 41 47 31 00 00 00 00 00 00 00 00 00 00 00 00 MAGI. 

Not found * 

The second entry is the only possible correct choice, since its address ends with “E.” 

When you think you have found the right one (or want to see if it is correct), subtract 
Hex lA from the address and list that address for 2 lines. If this is the entry you are 
looking for, you will notice that the first 4 bytes of the first and second lines contain the 
same mass memory address which must end in the number 4. When you have found this 
block, add Hex 12 to the address in the first 4 bytes of the first (and second) line. This is 
the location in mass memory where your user-written function code starts. 

In the example, lA is subtracted from 22928E to get 229274, then the following is typed 
in to examine this memory location: 

♦L 229274 229294 

00229274 00 22 97 84 00 22 8B E4 00 00 00 00 00 02 00 04 d. 

00229284 00 22 97 84 00 00 00 00 00 04 4D 41 47 31 00 00 .MAGI. . 
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Hex 12 is then added to the value found in the first 4 bytes: 

00229784 + 12 = 00229796 

This is the mass memory location of the beginning of the user-written function code. 

4. By adding the offset found in step 2 and the start address found in step 3, calculate 
the actual address of the code in question. 

00229796 + 2EC = 00229A82 

This is the address inside the code where you want to set the breakpoint. It is usually 
a good idea to check the contents of memory with what you expect them to be at this 
location. You can list the memory at the address you have calculated and compare 
the numbers with the numbers which represent the instructions given in your listing 
file. If they do not match, then you do not have the correct address. 

*L 00229A82 0229A92 

00229A82 20 6E FF FC 22 7C 00 00 00 00 B1 C9 67 00 02 7E n.i”i-llg.-T 


Compare the contents of memory location with what you expected to see (see listing 
excerpt in step 2 above) and see that you have found the correct address. 

5. Set breakpoint. Up to seven breakpoints can be set at one time. 

*BR 229A82 ♦ 

6. Type “G” to return to PS 300 run-time code. Just before the code is executed at the 
breakpoint location, the PS 300 wiU enter Debug mode. The picture on the display 
will go away, and the debug prompt as well as register contents will appear on the 
ASCII terminal screen. The program counter is listed with the registers. It is at the 
address of your breakpoint. 

7. Return to PS 300 run time by typing “G” at the terminal, or trace through subsequent 
instructions as desired. 
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NOTES 

While the PS 300 is in debug mode, all interrupts are disabled. Thus, any 
data entering the PS 300 from the host or peripheral devices will be lost. 
Therefore, make sure no data are coming in from the host at the time 
your breakpoint is executed. If your function relies on data from the 
host, one way to get around this problem is to: 


1. Place an F:SYNC(2) function in front of your function. 

2. Connect the input source to input <1> of the sync function and output 
<1> of the sync function to your user-written function. 

3. Set input <2> of F:SYNC to be a constant. 

4. When aU data from the host have arrived on input <1> of the sync 
function, send a message to input <2>. This will cause the data to 
pass through the sync function and cause your user-written function 
to be executed. 
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MODULE 8 

User-Written Function Reference 


Introduction 

This part of the manual is provided as a reference section for information you may need while 
writing your own functions. It contains the/oUowing sections: 



• Message Types Description of the legal message types that can be passed 

between functions. Also contains an excerpt from 
USERSTRUC.PAS that illustrates how the types are 
declared. 

• Utility Routines Topical listing and short description followed by the utility 

routines in alphabetical order. Advanced User-Written 
Fvmction procedures are described separately after the 
User-Written Function utilities. 


• Stack Usage List of the stack usage, in bytes, of the utility routines. 

• Error Messages A list and description of system error messages you might 

encounter while writing your own functions. 

These routines are aU declared in the E&S-provided file, USERSTRUC.PAS. The procedures 
themselves are in USERLINK.RO and must be linked to any function you write. 
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NOTE 

During tJie initial distribution of USERSTRUC.PAS, two versions were 
sent to customer sites. The difference in the two versions is in the names 
of the pointers and the PS\300 floating-point record definition. This 
release of USERSTRUC.PAS supports the following naming conventions, 
with the strong recommendation that the conventions in this manual be 
used: 

Preferred Acceptable 

Double PS 300 floating point 

UWFInQarray InUWFQarray 

The two names shown below are no longer acceptable and must be 

modified: 


Not Acceptable Must Be Modified To 

PtrInQarray PtrUWFInQarray 

InQarray UWFInQarray 
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Message Types 

The type declarations included in USERSTRUC.PAS define the various message types that are 
used in the PS 300, as well as other types that are used by the utility routines. This section 
describes these types and how to use them. 


QDtype and Qdata 


The QDtype is used to specify the different types of Qdata message blocks available in the 
PS 300 run-time system. Qdata blocks are the primary vehicle for communication 
between functions in the PS 300. 

The Qdata record declaration specifies the formats for all messages. The first field, Next, 
is a pointer to the next message in a list or queue of messages. Ordinarily, you should not 
use the Next field explicitly. Next is defined as Ptrqdata = tQ^ata; (pointer to a 
message}. Nearly all communication that takes place within the PS 300 runtime system 
occurs by passing message blocks (often referred to as Qdata blocks or a “Qdata”)* The 
Ptrqdata contains the pointer to a Qdata block. 

The Qtyp field indicates the QDtype of the message body. The remaining fields vary, 
depending on the contents of the Qtyp field. A general listing of the QDtypes follows: 


QDtype = { types of Qdata (message) blocks } 
( 


{ 0} 

Qreset, 

{ dataless: reset a function instance 

} 

{ 1} 

Qprompt, 

{ dataless: flush the Cl pipeline 

} 

{ 2} 

Qboolean, 

{ normal carrier of Boolean values 

} 

{ 3} 

Qinteger, 

{ normal carrier of integer values 

} 

{ 4} 

Qreal, 

{ normal carrier of floating point values 

} 

{ 5} 

Qstring, 

{ original carrier of byte strings, not used 

} 

{ 6} 

Qpacket, 

{ carrier of byte strings 

} 

{ 7} 

Qmorepacket, 

{ continuation Qpacket carrier of byte strings 

} 

{ 8} 

Qmove2, 

{ 2D vector including P bit 

} 

{ 9} 

Qdraw2, 

{’2D vector including L bit 

} 

{10} 

Qvec2, 

{ 2D vector with no P/L bit (normal vector) 

} 

{11} 

QmoveS, 

{ 3D vector including P bit 

} 

{12} 

QdrawS, 

{ 3D vector including L bit 

} 

{13} 

Qvec3, 

{ 3D vector with no P/L bit (normal vector) 

} 
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{14} 

Qmove4, 

{ 4D vector including P 

bit 


} 

{15} 

Qdraw4, 

{ 4D vector including L 

bit 


} 

{16} 

Qvec4, 

{ 4D vector with no P/L 

bit 

(normal vector) 

} 

{17} 

Qmat2, 

{ 2x2 matrix 



} 

{18} 

Qmat3, 

{ 3x3 matrix 



} 

{19} 

Qmat4, 

{ 4x4 matrix 



} 

{20} 

Qusertype 

{ type that user may use to 

define own message 

} 


) ; 


QDtype is padded with 260 miscellaneous elements to ensure that a 16-bit field is 
allocated by the Pascal compiler rather than the 8-bit field that would be allocated 
otherwise. 

Most of the QDtypes are self-explanatory. A few that may need more explanation 
follow. 

Qreset and Qprompt are not ordinarily used by user-written functions. Qstring is 
obsolete and remains in the PS 300 system for historical purposes only. You should use 
Qpacket for string messages. 

Qpacket is the standard byte/character message block. Although the Pascal declaration 
for a Qpacket indicates that the P_Cnt field will hold 255 characters, the actual amount of 
storage allocated varies. You should never attempt to reference characters outside of the 
P_Cnt[P_Beg..P_Lth]; doing so could cause a fatal error in the PS 300. If you need to 
append to the end of a Qpacket, you must allocate a new message large enough to hold 
the entire string. 

Qmorepacket is used as a continuation block for a message coming from the host with 
more than 255 bytes of information. Again, this message type is not used by ordinary 
functions. 

QuserType is available to allow users to define their own messages types, while still 
handling the messages uniformly within the PS 300 system. If you want QuserType 
messages to carry data, you must modify the declaration of the Qdata record type in 
USERSTRUC.PAS to include a variant for QuserType that contains the desired fields. 
QuserType’s Qtyp fields must be explictly filled in by the program. (Refer to F:SPIRO in 
Module 6 of this manual for an example of how to use QuserType messages.) 

The QData record declaration (from USERSTRUC.PAS) follows. 
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Intl6 = -32768..32767; { 16-bit integer } 

Qdata = 

RECORD 

Next: Ptrqdata ; { next message in a list of messages } 

CASE Qtyp: Qdtype OF { type of message } 

{ Qreset: no datum carried } 

{ Qprompt: no datum carried } 

Qboolean: 

( 

b: boolean 

) ; 

Qinteger: 

( 

i: integer 

) ; 

Qreal: 

( 

r: PS_300_floating_point 

) ; . 

Qpacket, Qmorepacket: { byte-string } 

( 

P_lth: int 16 ; { max byte number } 

P_beg: int 16 ; { min byte number } 

P_cnt: Bytespell { byte of message } 

) ; 

Qmove2, Qdraw2, Qvec2 

Qmove3, Qdraw3, Qvec3 

Qmove4, Qdraw4, Qvec4: 

( 

V4: Vector { all vectors use 4D indexing } 

) ; 

Qmat2, Qmat3, Qmat4: 

( 

Mat4: Matrix { all matrices use 4x4 indexing } 

) ; 

END ; { Qdata } 


Input Message Pointers 


o 


PtrUWFInQarray = fUWFInQarray; 

UWFInQarray = ARRAY [1..MaxInputQueues] of PtrQdata; 

UWFInQarray contains the pointer to the input queues for the userwritten function. 
PtrUWFInQarray contains the pointer to the UWFInQarray. 
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PS 300 Floating-Point Numbers 

In the PS 300, floating-point numbers are defined as 


Double 

c 

m 

not_used 

END; 


RECORD 

Intl6 ; { Exponent } 
Integer ; { Fraction } 
Intl6 { not used } 


where: 

c is the excess-1024 power of two of the number. 

m is the mantissa in M68000 internal type “long” interpreted as a two*s-complement 
number whose binary point is between bit 31 (the sign bit) and bit 30. 

The fraction is normalized; i.e., except for zero, the sign bit differs from the most 
significant bit. This normalization is accomplished by adjustment of the exponent for any 
shifts which might occur. Such adjustment can cause the exponent to exceed its 
maximum (overflow) or underrun its minimum (tinderflow). 

Because the fraction is stored as a two’s-complement number, overflow can occur when 
negating the negative number of largest magnitude. 

not_used is a field that is not used but must exist in all the floating-point records. This 
field is included in each floating-point record to ensure that data are aligned on 8-byte 
boundaries, a factor that can help improve some execution speeds. 

Examples: 

R : Double; 


R.c := 0 + 1024; 

R.m := 16384 65536; 

(This is number 1/2 * 2’''*0 = .5} 

R.c := -1+1024 ; R.m := -2147483648 
{This is the number -1 * 2**-l = -.5} 


Vector = ARRAY [0..3] of PS 300_Floating_Point; 

All vectors (2D or 3D) are allocated as 4D vectors of floating-point values to allow X,Y,Z 
and I to be accommodated, if required. When a vector becomes part of a display data 
structure, it has been optimized appropriately. 
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Matrix = ARRAY [0..3, 0..3] of PS 300_Floating_Point; 


All matrices (2x2, 3x3, 3x4, and 4x4) are allocated as a 4x4 matrix of floating-point 
values to allow all sizes of matrices to be accommodated, if required. When a matrix 
becomes part of a display data structure, it has been optimized appropriately. 


Bytespell = ARRAY [1..255] of CHAR; 

The Bytespell array is used to hold bytes/characters for Qpacket and Qmorepacket 
messages. 
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Topical Listing Of Utility Routines 


Input Queue Handling and Function Scheduling Procedures 


These procedures are provided to obtain access to input messages and control function 
scheduling. Functions are not required to look at all of the inputs, but there must be one 
message on each of the inputs for the function to run. The scheduling procedures are: 

Ckinputs 

Cleaninputs 


Error Reporting Procedures 


When a PS 300 function detects an error, a message is displayed. When this happens, 
the status of the messages on the input queues is the same as if the function had run to 
completion without an error. There is one exception: If the error was due to a message 
on a Cqueue, the message is removed. 

The supplied utility procedures provide for the basic needs of error reporting. They are 
not intended to cover all cases. If the proper error message routine does not exist, it is 
the programmer's option to write a new error routine that meets that need. 

The writer of the function is responsible for seeing that if one of these error routines is 
executed, flow immediately proceeds to the “IF Cleaninputs THEN” statement after all 
the inputs have been checked for errors. This follows the error philosophy that reqmres a 
function to have one complete input set to execute, and if anything is in error in that set, 
the function will not run. 

The following error handling procedures are provided in USERLINK. 

QIUMessage 

QlUValue 

Qincompatmsgs 

Systemerror 

UWFerror 
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Set_Cness Procedure 

There is one procedure provided to change the Cness or Tness of a function queue: 
Set Cness 


Private Data Queue Procedures 

Some functions require that data acquired during the process of the function be retained 
from execution to execution. These functions are referred to as having “private data 
queues”; that is, queues for data not fed from input to output during each execution 
cycle. No outside function can send messages to these queues. Procedures provided for 
functions with private data queues are: 

CkPrivate 

SavePrivate 


Message Management Procedures 

The following procedures are used to send, copy, or dispose of messages: 

DropMessage 

MsgCopy 

QSendCopyMess 

SendMsg 


PS 300 Floating-Point Utilities 

The procedures to perform floating-point computations are: 

FCadd 

FCdivide 

FCint2double 

FCinteger 

FCmultiply 

FCnearzero 

FCp2multiply 

FCround 

FCsquareroot 

FCsubtract 

Fpabs 

Fpecomp 

Sincos 
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Carving and Initialization Procedures 


The following procedures are used to carve and initialize new data types: 

Newqboolean 

Newqinteger 

Newqmatrix 

Newqnil 

Newqpacket 

Newqreal 

Newqvector 

Newtry 


Timing Procedures 

Csecs 

Frames 

Hitime 

Ticks 


String Handling Procedures 


Char_text 

Int_text 

Real_text 

Text_text 

Time_text 


Other Procedures Provided Via USERLINK.PAS 


My_in_out 

My_name 

Rndmnumber 

Vfetch 

Vstore 
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Procedures Provided Via USERLINK 


Cklnputs 

FUNCTION Cklnputs (Nmin, Nmax : Inti6) : PtrlnQarrary; 

Cklnputs sets a pointer to each of the input queues specified in the inclusive range Nmin to Nmax 
and stores them in an array. If there is a message on each of the input queues, it returns a pointer 
to the array and the function state is changed to MIDRUNNING. This signifies that the function 
may execute. The function returns NIL if there are queues in the range that do not have a 
message. When NIL is returned, the function is put into the MSG_WAIT state and must exit. 

A function does not have control over these input message blocks. For example, it cannot reuse 
an input message block. Data being sent out must be contained in newly created message blocks. 
If a function is to send a message through without change (such as F:SYNC), the utility procedure 
Qsendcopymess should be used for efficiency. 


Char_text 

PROCEDURE Char_text (c: char; VAR b,e: Intl6; VAR ca: Bytespell) ; 

FORWARD ; { TEXTUTIL.PAS } 

Char_text adds one character to a text string ca at location b+1 within that string but not beyond 
location e. b is updated. If b is negative, system error 81 is generated. 


CkPrivate 


FUNCTION CkPrivate : Ptrqdata; 

Ckprivate returns a pointer to the private message for this function, if it exists, or returns NIL if 
the private message does not exist. 
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Cleaninputs 


FUNCTION Cleaninputs : Boolean; 

Cleaninputs must be called after the input messages have been processed and the outputs have 
been sent. Its purpose is to “clean up” the input queues and determine whether the function may 
run again immediately. 

This procedure can recognize whether an input queue is a trigger queue (Tqueue) or a constant 
queue (Cqueue). It drops the first message from each Tqueue and leaves Cqueues unchanged. 

The function must be in the MID_RUNNING state when this utility procedure is called. If the 
function can run again immediately, Cleaninputs returns TRUE and the function state is set to 
RUNNING. If there are not enough input messages for the functions to run again, FALSE is 
returned and the function state is set to MSG_WAIT. It is also possible for Cleaninputs to return 
FALSE if the function has been running longer than 2 milliseconds; in this case, the state is set to 
ACTIVE and is required to give up control so that other functions can run. 


Csecs 


FUNCTION Csecs: Integer ; 

Csecs returns the number of centiseconds since the system was booted. 


DropMessage 

PROCEDURE DropMessage (VAR m: Ptrqdata) ; 

Dropmessage disposes of the message m. It should be used rather than DISPOSE for all message 
dropping—especially for dropping messages of unknown Qtype—since it knows when additional 
data items are affected by the message being dropped. The message m is no longer the property 
of the calling code, m is set to NIL. 

A function does not need to dispose of input messages explicitly since the procedure Cleaninputs 
disposes of them. 
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FCadd 

PROCEDURE FCadd (VAR augend, addend: Double; 

VAR sum: Double); 

FCadd does a floatmg-point add. 


FCdivide 

PROCEDURE FCdivide (VAR dividend, divisor: Double; 

VAR quotient: Double); 

FCdivide does a floating-point divide. If the divisor is zero, the function returns the largest 
positive number if the dividend is positive, otherwise it returns the largest negative number. 



FCint2double 

PROCEDURE FCint2double (num : Integer; VAR floated: Double); 
FCint2double makes a floating-point number from an integer. 


FCinteger 

PROCEDURE FCinteger (VAR innum: Double; VAR outnum: integer); 
FCinteger truncates a floating-point number to an integer. 


FCmultiply 

PROCEDURE FCmultiply (VAR a, b: Double; 

VAR product: Double) ; 

FCmultiply does a floating-point multiply. 

r\ 
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FCnearzero 

FUNCTION FCnearzero (VAR tiny : Double; negpower2 : Intl6 : Int8 ;) 

{ negpower2=l —> within .5; =2 —> within .25} 

Returns a byte that indicates if a number is close to zero given an absolute tolerance. 

The tolerance (negpower2) is expressed as the negative power of two; that is, 0 means that 
anything less than 1 is close enough, 

1 means anything less than .5 is close enough, 

2 means anything less than .25 is close enough, etc., 
and -1 means anything less than 2 is close enough, etc. 

Results mean: 

-1 means the number is not close to zero, and it is negative, 

0 means the number is close enough, 

1 means the number is not close to zero, and it is positive. 


FCp2multiply 

PROCEDURE FCp2multiply (VAR innum: Double; power: Integer; 

VAR outnum: Double) ; 

FCmultiply multiplies innum by 2 raised to the power specified by power, (i.e., power is added to 
the exponent of innum, hence power can be either positive or negative.) 


FCround 

PROCEDURE FCround (VAR Innum: Double; VAR outnum: Integer) ; 
FCround rounds a floating-point number to an integer. 


FCsqroot 

PROCEDURE FCsqroot (VAR a: Double;VAR sqroot: Double) ; j FCsqroot returns the square 
root of a positive floating-point number. If the number is negative, 0 is returned. 
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FCsubtract 

PROCEDURE FCsubtract (VAR minuend, subtrahend: Double; 

VAR difference: Double) ; 

FCsubtract does a floating-point subtract. 


Fpabs 


PROCEDURE Fpabs (VAR r: Double) ; 

Fpabs changes r to the absolute value. This is a destructive operation in that it changes r itself and 
does not put the absolute value in another variable. 



Fpecomp 

FUNCTION Fpecomp (VAR xl,x2: Double): Int8 ; 

Fpecomp compares two floating-point numbers and returns: 

-1 if xl < x2 
0 if xl = x2 
1 if xl > x2 


Frames 


FUNCTION Frames: Integer ; 

Frames returns the number of frames displayed since the system was booted. 
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HRTime 

PROCEDURE HRTime (VAR c,f,d: Integer) ; 

The HRTime procedure returns a high-resolution clock value. It returns the current time in 
centiseconds, and a fraction indicating the amount of time remaining until the next centisecond. 

It is mainly used to calculate the elapsed time between two events, as shown in the following 
example: 


HrTime (cO, fO, d); { initial high-resolution time } 


HrTime (cl, fl, d); { final high-resolution time } 

Elapsedtime := ((cl-cO)*d) + (fO-fl); { actual runtime of code } 

c is the current value of the centisecond clock, returned as a 32-bit integer which wraps around to 
zero, f/d is the fraction remaining until the next centisecond. Note that f decreases in value for 
increasing time, while c increases in value for increasing time. 


Int_text 

PROCEDURE Int_text (n: Integer; Ns,Nz: Intl6; 

VAR b,e: Inti6; VAR Ca: Bytespell) ; 

Int_text converts an integer to text, as a signed decimal number, and adds it to a text array, via 
Char_text. Ns is the minimum number of characters to generate, and Nz is the minimum 
number of leading zeros to print. (Note: to print n=0, Nz must be 1.) The number starts in 
Ca[b+1] and will not go beyond Ca[e]. b will be changed, e specifies last character which can be 
changed. If b is negative, system error 81 is generated. 


MsgCopy 

FUNCTION Msgcopy (m: Ptrqdata): Ptrqdata ; 

Msgcopy makes a copy of the message m. The message returned by Msgcopy is the property of 
the calling code and must be disposed of (Dropmessage) or handed on (Sendmsg) before the 
calling code returns. 
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My_in_out 

PROCEDURE My_.in_out (VAR NJn,N_out: Inti6) ; 

My__in_out reports the number of input queues and output ports for the current function instance. 


My_name 

FUNCTION My_name : Ptrqdata ; 

My_name looks up the name of the function instance and returns that name in a Qpacket. 



Newqboolean 

FUNCTION Newqboolean: Ptrqdata ; 

Newqboolean carves and initializes a Qboolean message. Initialization includes setting: Qtyp = 
Qboolean, value to FALSE. 


Newqinteger 


FUNCTION Newqinteger: Ptrqdata ; 

Newqinteger carves and initializes a Qinteger message. Initialization includes setting: Qtype = 
Qinteger, value to zero. 


Newqmatrix 

PROCEDURE Newqmatrix(Typ: Qdtype): Ptrqdata ; { Qmat2, ... } 

Newqmatrix carves and initializes a matrix message of type Typ and contents all zero (Note: not 
floating-point number zero). 
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Newqnil 

PROCEDURE Newqnil(Typ: Qdtype): Ptrqdata ; { Qreset; Qprompt } 

Newqnil carves and initializes a dataless message of type Typ. Initialization includes setting: 
Qtype = Typ 


Newqpacket 

PROCEDURE Newqpacket (Typ: Qdtype; { Qpacket or Qmorepacket } 

Nbytes: Inti6): Ptrqdata ; 

Newqpacket carves and initializes a Qpacket or Qmorepacket message large enough to hold 
Nbytes of information. Note that, although the Pascal declaration for a Qpacket indicates that the 
P\Cnt field will hold 255 characters, only Nbytes bytes are actually allocated by NewQPacket. 
You should never attempt to reference characters beyond the end of the string. Initialization 
includes setting: Qtype = Typ, P_lth = Nbytes, P_beg = 1, P_cnt[l..Nbytes] = 0 


Newqreal 


FUNCTION Newqreal: Ptrqdata ; 

Newqreal carves and initializes a Qreal message. Initialization includes setting: Qtype = Qreal, 
exponent and mantissa to zero (Note: not floating-point value zero). 


Newqvector 

FUNCTION Newqvector (Typ: Qdtype): Ptrqdata ; { Qvec2, ... } 

Newqvector carves and initializes a vector message of type Typ and contents all zero (Note: not 
floating-point number zero). 
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Newtry 

FUNCTION Newtry (num_bytes : Integer) : Rrqdata; 

Newtry returns a block of the specified length in bytes if one is currently available in the system. 
If one is not available, NIL is returned. This differs from all the other “Newq” functions that will 
not return until a block of the specified type is available (or eventually cause the system to crash 
with a trap 0). Newtry is used to carve data blocks when the function has a choice of what to do if 
a data block of sufficient size is not available. 



QIllMessage 

PROCEDURE QIllMessage (Inqueue : Inti6); 

The parameter Inqueue indicates the input queue that contains the bad message. QILLMessage 
prints the message: 

Message which function cannot handle. 

It then drops the message and sets INPUTSf. [inqueue] := NIL; 


QlllValue 

PROCEDURE QlUValue (Inqueue : Intl6 ); 

The parameter Inqueue indicates the input queue that contains the bad message. QillValue prints 
the message: 

Type okay but value out-of-range 
It then drops the message and sets INPUTSf. [inqueue] := NIL; 
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Qincompatmsgs 

PROCEDURE Qincompatmsgs (one : Inti6; theother : Inti6); 

The parameters indicate the input queues that are incompatible. This procedure prints the 
message: 

Incompatible message types detected by this function 
It then deletes the message on the queue theother and sets INPUTSt-[theother] := NIL; 


QSendCopyMess 

PROCEDURE QSendCopyMess (inqueue, outqueue: Intl6); 

QSendCopyMess takes the message on the specified Inqueue and sends it unchanged on the 
specified Outqueue of the function. If the queue is a Cqueue, a copy of the message is sent. If 
it’s a Tqueue, the message is removed and sent. 

NOTE 

Consuming a message results in INPUTS506. [Inqueue] := NIL and any 
following references to INPUTS506. [Inqueue] will produce 
unpredictable results. Because of this, it is recommended that 
QSendCopyMess only be used prior to the “IF Cleaninputs THEN” 
statement. 


ReaMext 

PROCEDURE RealText (VAR r: Double;VAR b,e: Intl6; 

VAR Ca:Bytespell); 

Real_text converts r into text, expressing roughly 5 digits. If possible, r is printed as a fixed point 
number, but if it is too small or too large, it is printed in exponential form. The real number will 
be written starting at Ca[b+1]. b will be changed, e specifies the last character that can be 
changed. If b is negative, system error 81 is generated. 
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Rndmnumber 

FUNCTION Rndmniimber (seed : Integer): Intl6; 

Returns a pseudo-random 16-bit number. If the value of the seed is zero, then the value 
returned is computed based on the current seed value. If the passed seed value is non-zero, then 
it is made into the current seed and then the number is computed. The linear feedback shift 
register technique uses a 31-bit seed (bits 31 to 1) with taps on bits 31 and 6. This algorithm does 
7 bits at a time (3 times for 16 bits). It does not repeat until 2^31 - 1 iterations. 


SavePrivate 

PROCEDURE SavePrivate (msg : Ptrqdata); 

This utility procedure is used for filling the Private queue, a queue to which no outside function 
can send messages. Once a message has been saved on the private queue, it will remain there as 
long as the function exists. The value, however, can be changed, and the queue will then retain 
the new value. 


SendMsg 

PROCEDURE SendMsg (VAR m: Ptrqdata; o: Inti6) ; Sendmsg sends the VAR m to any and 
air other named entities connected to the function’s output port <o>. After this is done, the 
message m is no longer the property of the calling code and m has value NIL. 


Set_Cness 

PROCEDURE Set_Cness (input : Intl6; cqtype: Boolean); Set_Cness allows the function itself to 
do the SETUP CNESS TRUE/FALSE<i>a; command, input is the input number of the function 
that the Boolean value will be sent to. ctype is the Boolean value: TRUE sets the specified input 
to a Cqueue and FALSE sets the specified input to a Tqueue. By default, when a function is 
instanced, all input queues are Tqueues. 


WARNING 

Using this procedure inside the function, as well as sending the SETUP 
CNESS command to the function, may produce unpredictable results 
because it may not be clear which code is executed last. Either one 
method or the other should be used, not both. 
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Sincos 

PROCEDURE Sincos (Angle: integer; VAR sine: Double; 

VAR cosine: Double; 

Sincos computes the sine and cosine of an angle, angle is an integer between 0 and 65535, 
corresponding to the range 0 to 2*pi radians. It computes the sine of angle by using the most 
significant 8 bits to index into a table of values and using linear interpolation of the least 
significant 8 bits. If angle is not in the first quadrant, it is converted to an angle in the first 
quadrant using trigonometric relations. 

RESULT := TABLE(A) + B * 256 * (TABLE(A + 1 ) - TABLE(A)) 

A = most significant 8 bits of angle 
B = least significant 8 bits of angle 

The cosine is computed by adding 90 degrees to the angle, then computing the sine. 


Systemerror 


PROCEDURE Systemerror (n: Inti6) ; 

Systemerror crashes the PS 300 with a TRAP 6. The parameter n becomes the system error 
number. There is no return from a Systemerror call. 


Text_text 

PROCEDURE Text^text (VAR B1,E1: Intl6; VAR Cal: BytespeU; 

VAR B2,E2: Intl6; VAR Ca2: BytespeU) ; 

Text_text wiU copy characters from Cal to Ca2 starting from Bl+1 in Cal into B2+1 in Ca2 and 
continuing until either Cal[El] has been copied or Ca2[E2] has been changed, at which point 
copying stops. Both B1 and B2 are changed. If B1 is negative. System error 80 is generated. 


Ticks 


FUNCTION Ticks: integer ; 

Ticks returns the number of ticks (Une-clock ticks 120Hz or 100 Hz) since the system was 
booted. 
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Time_text 

PROCEDURE Timejext (n: integer; VAR b,e: Intl6; VAR Ca: BytespeU) ; 

Time_text converts n number of seconds to text as a time. In the form: dd hh:mm:ss. The time 
string will be written starting at Ca[b+1]. b will be changed, e specifies the last character which 
can be changed. If b is negative, system error 81 is generated. 


UWFerror 

PROCEDURE UWFerror (VAR msg : Ptrqdata); 

UWFerror allows the user-written function to display any type of error message desired, msg 
must be a Qpacket containing the characters of the message to be printed, msg is set to NIL by 
the procedure. 


Vfetch 

FUNCTION Vfetch (name: Ptrqdata) : Ptrqdata; { a Qpacket } 

Vfetch fetches the contents of a named variable. The name of the VAR is supplied in name 
(Qpacket). If any error is detected, Vfetch returns NIL. Otherwise, Vfetch returns a copy of the 
message stored in the specified VAR. The returned message is owned by the function. 


Vstore 

PROCEDURE Vstore (name: Ptrqdata; VAR new_val: Rrqdata) ; 

Vstore stores the Qdata new_val into a named variable. The name of the variable is supplied in 
name (must be a Qpacket). If the store succeeds, new_val is set to NIL and is no longer owned 
by the function. Otherwise it is left alone. 
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Advanced UWF Procedures 


Lk cursuffix 


FUNCTION Lk_cursuffix( 

Nlth: integer; { name length } 

VAR Nspell: Namespell { name to be looked up } 

): Ptralphablk; 

Lk_cursuffix returns a pointer to the block of memory that contains the name of an object and 
pointers to its definition. The suffix of the currently running function is appended to the end of 
the characters in Nspell. If the name currently exists a pointer to it is returned. If it does not 
exist a new name block is created and the pointer to that is returned. This routine can then 
introduce new names into the system. Since names may be multiply referenced, a usage count is 
maintained. Only when that usage count goes to zero is the name block disposed. IT IS VERY 
IMPORTANT TO KEEP THIS COUNT ACCURATE! If the count is too small it will crash the 
system at some later time, if it too large the memory will never be recovered. Since this routine 
returns another reference to the name, the usage count has been incremented for that value. If 
the reference is not stored, when finished the usage count should be decremented. Changing the 
usage count is done through the routines Incausage and Decausage. Nlth is the number of 
characters in the name and Nspell is the array of character for the name. 

NOTE: all names are uppercase, so any lowercase letters in Nspell will be changed to uppercase. 


Lk nosuffix 


FUNCTION Lk_nosuffix( 


length: Integer; 

{ name length NOT counting suffix } 

Cinum: IntS; 

{ creating Cl } 

suffix: Char; 

{ the user suffbc } 

VAR NspelhNamespell 

{ name to be looked up } 

): Ptralphablk; 



Lk_nosuffix performs the same task as Lk_cursuffix except it is more general. Cinum is the 
number given to the name if it is created. This is used for such things as the INITIALIZE 
command. A Cl may only initialize those things which it has created. Suffix is the suffix 
character added to the name. ‘O': user 1 hidden names, ‘1': user 1 accessible names, ‘2': user 2 
hidden names, ‘3': user 2 accessible names. Nspell contains the character string of the name. 
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Lgaupdate 


PROCEDURE Lgaupdate ( 

name; Ptralphablk; 
data: Ptmamedentity; 
VAR Uph.Upt: Ptravupblk 
); 


{ alpha of object to change } 

{ new data to be referenced } 

{ head and tail of list of updates} 


Lgaupdate includes an update request onto a list of updates which are to be performed. Updates 
are identification for the display processor that an object is to change. This procedure creates the 
proper information so that the name of the element pointed to by ‘name’ will have its data 
changed to now point to ‘data*. The value for ‘name’ is obtained through the use of the 
Lk_cursuffix routine. 

This routine can be called several times followed by a call to Announceupdate. 

NOTE: uph and upt must be initialized to NIL prior to the first call of this routine. 


Announceupdate 


PROCEDURE Announceupdate ( 

VAR Uph,Upt: Ptravupblk { head and tail of list of updates } 

); 


Announceupdate takes the list of updates generated through the use of the Lgaupdate function 
and passes them to the display processor such that on the next frame the new definitions will be 
displayed and the old ones deleted. 


Msgstore 


PROCEDURE Msgstore ( 

Msg: Ptrqdata; 
a: Ptralphablk; 
n: integer 
); 


{ pointer to message block } 
{ alpha to receive message } 
{ input to receive message } 


Msgstore is used instead of Sendmsg when the message is to be sent to a known destination and 
input and not to the list on one of the functions outputs. Msg is the message to be sent. 

NOTE: even though it is not a VAR parameter, msg is used just like in Sendmsg so the caller 
should treat it just as though it was set to NIL by Msgstore. a points to the name block for the 
recipient and n is the input number. 
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PROCEDURE Setlock( 

VAR x: Lock 

): 

Setlock sets a lock to be True. 


Setlock 

{ lock to be changed } 



Clrlock 

PROCEDURE Clrlock( 

VAR x: Lock { lock to be changed } 

); 

Clrlock sets a lock to be False. 


Incausage 

PROCEDURE Incausage ( 

a: Ptralphablk { alpha to be incremented } 

): 

Incausage increases the usage count of a name block by one. 


Decausage 

PROCEDURE Decausage ( 

a: Ptralphablk { alpha to be decremented } 

): 

Decausage decreases the usage count of a name block by one. If the usage count becomes 0 the 
name block and data pointed to by the name block is disposed. 
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AcpProof 


PROCEDURE AcpProof( 

VAR location: ptracpcblk; { pointer to be replaced } 
newval: ptracpcblk { new pointer } 

); 


Acpprfl 


PROCEDURE Acpprfl ( 

VAR location: ptrsavstate; {pointer to be replaced } 
value: ptrsavstate { new pointer } 

); 

AcpProof, Acpprfl allow the changing of pointers directly without going through the normal 
update mechanism. Since pointers are 32 bits and the 68000 only writes 16 bii> at a time, this 
procedure writes the new pointer in such a way that if the display processor is reading at the same 
time it is being written, the worst that could happen is that it would appear as a NIL pointer and 
the display processor will terminate traversal at that point and return to another branch it has to 
traverse. This means you may loose part of your picture for one frame. If the UWF does not use 
this routine and writes the new value directly, the display processor may be sent to a random 
place in memory and almost guarantee that memory will be corrupted. 


OLbaddtoset 


PROCEDURE OLbaddtoset( 

A_son: Ptralphablk; 
A_father: Ptralphablk; 
VAR Uph, Upt: Ptravupblk; 
VAR Error: boolean; 

Optimize : boolean 

); 


{ alpha of branch to be added } 

{ alpha of set node } 
a head and tail of list of updates} 
{ status on return } 

{ optimize structure in effect } 


OLbaddtoset adds another branch in the traversal tree. Setnodes are the points in the traversal 
where the display processor branches and also the point at which saving the state and restoring it 
are performed. The recommended way of initially creating one of these branches is to Lgaupdate 
A_father to point to a Setnode which has had all of its pointers set to NIL. Olabaddtoset is called 
to add the first and all subsequent branches at this point. A__son points to the beginning of the 
new branch. A_father points to the name of the Setnode (branch). Uph and Upt are the list of 
updates generated, just as Upt and Uph of Lgaupdate. Hence for the change to actually appear 
Announceupdates must be called. Error is returned TRUE if Father is not a set node. Optimize 
should be TRUE if the operation should be treated as though OPTIMIZE STRUCTURE; was in 
effect, otherwise it should be FALSE. 
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Removefromset 


PROCEDURE Removefromset( 

A_father: Ptralphabik; 
A_son: Ptralphabik; 
VAR Uph, Upt: Ptravupblk; 
VAR Error: boolean 
): 


{ alpha of set node } 

{ alpha of branch to remove } 

{ head and tail of list of updates } 
{ status on return } 


Removefromset removes the branch of A_father which points to A__son. Uph and Upt are the list 
of updates generated, just as Upt and Uph of Lgaupdate. Hence, for the change to actually 
appear Announceupdates must be called. Error is returned TRUE if Father is not a set node. 


FetchBlock 


FUNCTION FetchBlock( 

block: PtrNamedentity; { pointer to block for which } 

{ updated values are desired } 
upt: Ptravupblk { tail of list of updates } 

): Ptmamedentity; 

Fetchblock searches the set of updates pending and returns a copy of block which has all updates 
applied to it. block is the pointer to the block for which updated values are desired, upt should 
be NIL unless some updates have been generated which have not yet been ‘announced*. 


Acp_v3f 


PROCEDURE Acp_v3f( 

VAR v: Vector; 
VAR acpv: Vec3f; 
pi: boolean 
): 


{ vector to be converted } 
{ APC format result } 

{ position/line } 


Acp_v3f converts a GCP format vector v to Vec3f0 format which' is the format for 3D 
vector-normalized vectors. IF pi is TRUE the vector is a line, if FALSE the vector is a position. 
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Acp_v2f 


PROCEDURE Acp_v2f( 

VAR v: Vector; 

VAR acpv: Vec2f; 

pi: boolean 

): 


{ vector to be converted } 
{ APC format result } 

{ position/line } 


Acp_v2f converts a GCP format vector v to Vec2f0 format which is the format for 2D 
vector-normalized vectors. IF pi is TRUE the vector is a line, if FALSE the vector is a position. 


Acp_v3b 



PROCEDURE Acp_v3b( 

VAR v: Vector; 
VAR acpv: Vec3b; 
pi: boolean; 
exp: Inti6 
); 


{ vector to be converted } 
{ APC format result } 

{ position/line } 

{ exponent to use } 


Acp_v3b converts a GCP format vector v to Vec3b0 format which is the format for 3D 
block-normalized vectors. IF pi is TRUE the vector is a line, if FALSE the vector is a position, 
exp is the exponent for the entire block. If exp is too small for a vector a fatal error will occur. 


Acp_v2b 


PROCEDURE Acp_v2b( 

VAR v: Vector; 
VAR acpv: Vec2b; 
pi: boolean; 
exp: Intl6 
): 


{ vector to be converted } 
{ APC format result } 

{ position/line } 

{ exponent to use } 


Acp_v2b converts a GCP format vector v to Vec2b0 format which is the format for 2D 
block-normalized vectors. IF pi is TRUE the vector is a line, if FALSE the vector is a position, 
exp is the exponent for the entire block. If exp is too small for a vector a fatal error will occur. 


n 
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nStoreVector 


PROCEDURE nStoreVector ( 


VAR block: Ptmamedentity; 

{ block to store vector in } 

VAR v: Vector; 

{ the vector } 

pi: boolean; 

{ position or line? } 

firstblock: Ptmamedentity 

{ first block in list for } 

): 

{ block-normalized } 


nStoreVector is the recommended way to create vector lists. Initially create the first block with 
nNewAcpdata and then use nStoreVector to put all vectors into the data block. Block is the 
current block to which items are added. Initially block = firstblock but may change as vector? are 
added, v is the vector to be added, pi is TRUE if the vector is a line and FALSE if it is a 
position, firstblock is the pointer returned by nNewAcpdata and is the pointer to be used for 
Lgaupdate. DO NOT PASS the same variable for both block and firstblock as this procedure may 
generate a linked list for this particular vector list. 


nNewAcpdata 


FUNCTION nNewAcpdata ( 

n: inti6; { number of elements } 

t: Dattype { data type of block } 

): Ptmamedentity ; 

nNewAcpdata carves the requested data type to the appropriate size, n is the number of 
elements, vectors or characters, t is the type of namedentity, vec3f0, vec2f0, dstring, etc. 


Store3x3 


PROCEDURE Store3x3( 

VAR m: Matrix3; { GCP format matrix } 

Ob: Ptmamedentity; { pointer to matrix operate node } 
n: intl6 { offset into operate node to begin store } 

): 


Store3x3 converts the GCP format matrix and stores it into a Matcon3 operate node which has 
been previously created starting at the location specified by n. 
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Store4x4 


PROCEDURE Store4x4( 

VAR m: Matrix4; { GCP format matrix } 

Ob: Ptmamedentity; { pointer to matrix operate node } 

n: inti6 { offset into operate node to begin store } 

): 


Store4x4 converts the GCP format matrix and stores it into a Matload4 operate node which has 
been previously created starting at the location specified by n. 


Drop_name 


PROCEDURE Drop__name( 

a: Ptralphablk { name to remove from dictionary } 

): 


Drop_name removes the name block a from the dictionary such that Lk_cursuffix and 
Lk__nosuffix will not be able to located it. 

fy - 

GetVector 


PROCEDURE GetVector( 

block: Ptmamedentity; 

{ from which block } 


index: Inti6; 

{ which vector } 

VAR 

v: Vector; 

{ returns the vector } 

VAR 

pi: Boolean 

{ is it a draw? } 


); 


GetVector converts a display processor format vector into a GCP format vector, block is the 
block which contains the vector, index is the number of the vector within that block, v is the GCP 
format returned vector and pi is returned TRUE if it is a line and FALSE if it is a position. 


Rawbacopy 


PROCEDURE Rawbacopy ( 

Mbytes: inti6; { number of bytes to copy } 

VAR Inba,Outba: intS { input and output buffers } 

); 

n ’- 
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Rawcbcopy 


PROCEDURE Rawcbcopy ( 

Nbytes: inti6; ^ { number of bytes to copy } 

VAR Inbatchar; { input buffer } 

VAR Outba: int8 { output buffer } 

): 


Rawcbcopy 


PROCEDURE Rawcbcopy ( 

Nbytes: inti6; { ntimber of bytes to copy } 

VAR Inba,Outba: char { input and output buffers } 

); 


The above procedures allow for the copying of bytes from one block to another. PASCAL can be 
tricked by selecting the appropriate data types for Inba and Outba according to the particular 
need. 


Size of 


FUNCTION Size_of( 

b: Ptmamedentity { pointer to block to check } 

): integer; 

Size_of returns the number of bytes available in the particular chunk of memory, b can be any 
type of element: Ptralphablk, Ptmamedentity, etc. It must be declared properly for PASCAL to 
accept it. 



FetchAdnum 

FUNCTION FetchAdnum ( 

f: Ptmamedentity; { pointer to Named Entity for whose } 

{ .Adnum field search is being made } 
aupt: Rravupblk { tail of list of updates } 

): Intl6; 

FetchAdnum searches and returns the current .Adnum (count) field of the pointer namedentity 
which will be its value once all updates have been performed, f is the Ptmamedentity for whose 
.Adnum field the search is being made, upt should be NIL unless there are updates which have 
not been ‘announced*. 
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nFetchCopy 


FUNCTION nFetchCopy ( 

block: PtrNamedentity; 
start: Inti6; 
coTint: Intl6; 
upt: Ptravupblk 
) : PtrNamedentity; 

nFetchCopy searches the update list to return a current copy of the particular block of a vector list 
as it will be when all updates are completed, block is the block as currently in memory, start is 
the index of the vector to start at, count is the number of vector to return, upt should be NIL 
unless the function has updates which have not been ‘announced*. The function returns a block 
which contains the vector lists requested. 


{ vec list to copy from } 

{ vector to start at } 

{ how many vectors to copy } 
{ update list tail} 


WaitFrame 


PROCEDURE WaitFrame ( 

framecnt : integer { number of frames to wait } 

); 


WaitFrame puts the function in I/O wait and waits for the number of frames specified in framecnt 
before reactivating the function. 


loc chead 


FUNCTION loc_chead : Ptrcommhead; 

Loc_chead returns a pointer into mass memory of the location of the Commhead. 


ptr_dcb 


FUNCTION ptr_dcb : Ptrdcb; 

Ptr_dcb returns a pointer into mass memory to the current users DCB. 
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DropNE 


PROCEDURE DropNE ( 

f : Ptmamedentity { name to be disposed of } 

); 


DropNE disposes of the Named Entity f and any associated blocks. 


Newre turns 


PROCEDURE Newretums( 

givemenil : boolean { return NIL when not enough memory } 

): 


Newretums sets a flag that tells the free storage routines how to handle a request for memory if 
there isn’t enough to grant the request. If givemenil is TRUE and there is not sufficient memory a 
NIL pointer is returned on the request. If givemenil is FALSE then the free storage routines will 
wait for a block to become available (eventually crashing the system if not found). Any NEW that 
needs to have this flag set TRUE should be followed immediately with a call to this routine to set it 
FALSE for other functions. 


Reactivate 

PROCEDURE Reactivate ;Reactivate puts the current function on the active list. The function 
must exit immediately after this procedure call. 


Myanyoutputs 


FUNCTION Myanyoutputs ( 

n: int8 { output number to check } 

): Boolean; 

Myanyoutputs checks the output specified in n to see if there are any connections to that output. 
If there are no connections a FALSE is returned. This can be used to determine the usefulness of 
doing some large calculation for an output that has nothing connected to it. 
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Pushmyinput 


PROCEDURE Pushmyinput ( 

m: Ptrqdata; { data to be pushed on input } 

n: Int8 { input number to push data on } 

); 


Pushmyinput causes the data pointed to by m to become the first message on the input queue n. 


WaitCsec 

PROCEDURE WaitCsec ( 

cseccnt ; integer { number of centiseconds to wait } 

): 

WaitCsec puts the function in I/O wait and waits for the number of centiseconds specified in 
cseccnt before reactivating the function. 
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Stack Size 

This section contains the rough stack usage estimates of the majority of the utility 
routines. It is necessary to estimate the total stack usage of a user-written function during 
the transfer of the user-written function from the host to the PS 300. This estimate is 
used to allocate stack space for use during subsequent execution by the user-written 
function. 

It is very important that adequate stack size be allocated for any function you write. 
Failure to do so will cause the PS 300 to crash when the function is activated. It is better 
to overestimate the stack requirements that to underestimate and risk a crash. 

A good initial estimate is 500 to 1000 bytes. This allows for the overhead of the utility 
routines and for an ordinary number of local variables. If your function has many local 
variables, especially matrices or large arrays, you should add the memory requirements 
for these variables. If you have included local procedures that may be called recursively, 
you should multiply the amount of stack usage for each procedxire by the maximum depth 
of recursion and add that amount to the total. 

A stack size of 1000 bytes is adequate for all of the function examples included in this 
manual with the exception of F:BEZIER, which requires about 5000 bytes. 


Procedure Stack Use In Bytes 


CSecs 

22 

Char_text 

22 

Ckinputs 

36 

Cleaninputs 

42 

DropMessage 

22 

FCadd 

22 

FCdivide 

22 

FCinteger 

22 

FCint2double 

22 

FCmultiply 

22 

FCnearzero 

22 

FCp2multiply 

18 
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(Rough stack, usage estimates continued.) 


Procedure 

Stack Use In Bytes 

FCround 

18 


FCsqroot 

22 


FCsubtxact 

18 


Fpabs 

22 


Frames 

22 


HRtime 

18 


Int_text 

52 

(1 character) 

Int_text 

94 

(2 characters) 

Int__text 

290 

(10 characters) 

MsgCopy 

40 


My_in__out 

18 


My__name 

66 


Newqboolean 

24 


Newqinteger 

24 


Newqmatrix 

26 


Newqnil 

26 


Newqpacket 

28 


Newqreal 

24 


Newqvector 

32 


Newtry 



QSendCopyMess 

240 


QIUMessage 

140 


QlUValue 

140 


Qincompatmsgs 

154 


Real_text 

310 

(E-format) 

Real_text 

293 

(F-format) 

Rndmnumber 

22 


SendMsg 

152 


Set_Cness 

180 


Sincos 

22 


Text_text 

42 


Ticks 

22 


Time_text 

134 


UWFerror 

22 


Vstore 

124 
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Error Messages 

The following list gives the error message, a brief description, and a short summary of what might 
have caused the error. It is provided as a simple guideline to some of the more common mistakes 
made in writing functions. A complete list of PS 300 errors is given in Appendix K. 

ERROR DESCRIPTION COMMON CAUSE 

TRAP 0 Out of memory Forgetting to call DropMessage on 

item generated by function and not 
sent as a message. 

TRAP 10 Possible multiple Using SendMsg on an input message. 

dispose 


SYSTEMERROR #D9 


Using Dropmessage on an input 
message. 

Overwriting a Qdata boundary. 
Call to Ckinputs has Nmin < 0. 


SYSTEMERROR #DA 

SYSTEMERROR #DB 


Call to Ckinputs has Nmin > Nmax. 

Call to Ckinputs has Nmax > total 
number of inputs for function. 


SYSTEMERROR #DE Multiple call to QSendCopyMess on the 

same input. 

SYSTEMERROR #E0 Function was not in state running when 

Ckinputs was called. 

Cleaninputs returned a FALSE and still 
called Ckinputs. 

Cleaninputs was not called before calling 
Ckinputs the second time. 
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ERROR 

SYSTEMERROR #E1 


SYSTEMERROR #E9 

SYSTEMERROR #EA 


DESCRIPTION COMMON CAUSE 

Function was not in state mid_running 
when Cleaninputs was called. 

Cleaninputs was called even though 
Ckinputs had returned a NIL. 


QIllMessage, or QlUValue was called for 
input which does not exist. 


QIllMessage, or QlUValue was called for 
input which was already dealt with. 

Previous call to QIllMessage, QlUValue, 
or QSendCopyMess. 
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APPENDIX A 

Using the Command Files on DEC VAXAHMS 


This appendix describes the files supplied on magnetic tape to users in DEC VAX/VMS 
environments and provides such a user with information on the use of the files and special 
downloading instructions. It contains a list of the various files created by the Motorola 
cross-software. The final section of this appendix contains a listing of the code for the command 
file that is used to call the Motorola cross-software and name the function. The list below is a 
complete description of the files distributed on the magnetic tape to support the User-Written 
Function facility under DEC VAX/VMS: 


Example Files: 



BEZIER.PAS 

CHCASE.PAS 

COUNT.PAS 

MAG.PAS 

SPIRO.PAS 

SPSTRUC.PAS { USERSTRUC.PAS modified to include Userdatatype } 


E&S-Provided Files to Support User-Written Functions: 


USERLINK.ASM 

userlink.ro 

USERSTRUC.PAS 


E&S-Provided Cross-Software Command Files: 


XASM.COM 

XPASCAL.COM 

XPASCAL2.COM 

XLINK.COM 

XBUILD.COM 

XL.COM 

XNAMES.COM 
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Motorola Cross-Software Files: (if purchased through E&S ) 


XASM.EXE 

XPASCAL.EXE 

XPASCAL2.EXE 

XLINK.EXE 

pascalib.ro 

XASMINIT.DAT 


Using the Cross-Software on VAX/VMS 


Before attempting to use the cross-software, users should edit their LOGIN.COM file to 
invoke XNAMES.COM, which defines the necessary commands and logical names. This 
allows the assembler, compiler, and linker to be used exactly as described in the 
EXORMACS manuals. Before executing any of the commands described below, you 
should set your default directory to the directory containing the source files for the 
function you wish to compile and link. This directory should also contain copies of 
USERSTRUC.PAS and USERLINK.RO. As a convenience, a command file XL.COM 
has been provided to compile and link a user-written function, and produce the S-record 
file ready to download to the PS 300. All of the code must be contained in a single .PAS 
file, and the name of the function is assumed to be the name of the file. To invoke this 
command file, you should enter a command of the form: 


$ XL <filename> <number inputs> <number outputs> <stack size> 


If your function contains code from more than one .PAS file, or if you wish to include 
routines you have written in assembly language, you will have to follow these steps: 

(1) Compile Pascal source files: 

$ XPAS <filename> 

$ XPAS2 <filename> 


(2) Assemble assembly-language source files: 

$ XASM <filename> 

(3) Link the object files into an S-record file: 

$ XLINK <filenamel>/<filename2>../userlink,<filenamel>,<filenamel>;himx 

(4) Add the function header line to the S-record file: 

$ XBUILD <filename> <number inputs> <number outputs> <stack size> 
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Special Software Installation Instructions for DEC VAX/VMS 

These two steps should be taken prior to using the command files and the cross-software: 

1. You should edit XNAMES.COM so that the logical names XEXEDIR and XCOMDIR 
reflect the actual directories where the cross-software executables and command files 
(respectively) have been installed. 

2. You should make sure that all of the files are publicly readable. 

Files Created by the Motorola Cross-Software 


File Description 

Contents 


<filename>.PAS 

Pascal source file. 


<filename>.PC 

P-code output from pass 1 of the Pascal compiler and input 
to pass 2. 

<filename>.Pl 

Listing produced by pass 1 of the Pascalcompiler. 


<filename>. A S M 

Assembly-language source file. 


<filename>.LS 

Listing file produced by assembler or pass 2 of the 
compiler. 

Pascal 

<filename>.RO 

Object file output by assembler of pass 2 of the 
compiler, input to the linker. 

Pascal 

<filename>.SR 

S-record file created by the linker. 


<filename>.LL 

Link map output by the linker. 


<filename>.300 

S-record file with header information included. 



DEC VAX/VMS Command Files 

This section contains the code for the DEC VAX/VMS command files that are supplied 
on magnetic tape by E&S to support the User-Written Function facility. 

1. XASM.COM 
$ ! 

$ ! Motorola 68000 Cross-Assembler 
$ ! 

$ ! The cross-assembler may be used exactly the same as on 
$ ! the EXORmacs. Note that the source file must reside in the 
$ ! directory where the cross-assembler is called from, the file 
$ ! extension must be .ASM, and the user must NOT specify any other 
$ ! file extensions. 

$ ! 

$ open/write il inputline.dat 
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$ write il 
$ close il 
$ ! 

$ ! Now cause cross software execution 
$ I 

$ assign xasminit.dat INITFILE 
$ copy xexedir:xasminit.dat xasminit.dat;9999 
$ on error then goto finish 
$ on control_y then goto finish 
$ ! 

$ run xexedir:xasm 
$ finish: 

$ delete xasminit.dat;9999 
$ delete inputline.dat;* 

$ deassign initfile 
$ exit 

2. XBUILD.COM 


$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 


XBUILD.COM — build S-record .300 file for a UWF 

This command file builds an S-record file for a UWF which is ready to 
download to the PS 300. The header information is found and added to 
the front of the output file from the linker. 

You should execute this command file from the directory containing the 
files for the UWF. The name of the UWF is assumed to be the same as 
the name of the files. The .LL and the .SR files produced by the 
linker must be present. An extension of .300 is used for the output 
file. 

Parameters: 

pi = name of UWF 
p2 = number of function inputs 
p3 = number of function outputs 
p4 = estimated stack size 


$ 


$ 

$ 

$ 

$ 

$ 

$ 


Ask the user for parameters if none were supplied. 


if pi .eqs. 
if p2 .eqs. 
if p3 .eqs. 
if p4 .eqs. 


then inquire pi "Name of UWF" 

"" then inquire p2 "Number of function inputs" 
"" then inquire p3 "Number of function outputs" 
"" then inquire p4 "Estimated stack size" 


$ 

$ 

$ 

$ 


Determine the length of the code produced. This is found in the link 
map (the .LL file). Note that the following commands depend on 
knowing the exact format of the link map. 
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$ ! 

$ search /output=lsearch.tmp 'pl^.LL "Total Length" 

$ open /read tmp Isearch.tmp 
$ read tmp length 
$ close tmp 

$ delete Isearch.tmp;0 
$ length := 'f$extract(24, 13, length) 

$ ! 

$ I 

$ ! Write the .300 file. This involves writing out the header, doing some 
$ ! extra stuff to make sure VMS gives it the right file attributes, and 
$ ! then appending the S-record file (.SR) and a semicolon. 

$ ! 

$ open /write header fun.tmp 

$ write header ""length' "pi' "p2' "p3' "p4'" 

$ close header 

$ assign /user fun.tmp sys$input 
$ create 'pi'.300 
$ append 'pl'.sr 'pi'.300 
$ open /append fun 'pi'.300 
$ write fun ";" 

$ close fun 
$ delete fun.tmp;0 

$ write sysScommand ""pi'.300 created" 

$ exit 


3. XL.COM 

$ ! XL.COM — command file to compile and link UWFs 
$ ! 

$ ! This command file compiles and links a user-written function, 

$ ! producing an S-record file ready for downloading to the PS 300. 

$ ! The function must be contained in a single Pascal source file; 

$ ! the name of the function is the name of the source file. 

$ ! An extension of .PAS is assumed for the input file, and an 

$ ! extension of .300 for the output S-record file. 

$ ! You should execute this command file out of the directory containing 
$ ! the Pascal source file for the user-written function. 

$ ! 

$ ! Parameters: 

$ ! pi = name of uwf 

$ ! p2 = number of inputs 

$ ! p3 = number of outputs 

$ ! p4 = estimated stack size 

$ ! 

$ on error then exit 
$ on control_y then exit 
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$ ! 

$ ! Compile and link the UWF, using Motorola 68000 cross-software. You can 
$ ! detect compilation errors by checking for a 0-length .PC file. 

$ ! 


$ if pi .eqs. then inquire pi "Name of UWF" 
$ xpas 'pl^ 

$ pcfile := 'pi'.pc 

$ if 'f$file attributes(pcfile,"ALQ") .eq. 0 - 
then goto bugs 
$ xpas2 'pi' 

$ xlink 'pl'/userlink,'pi','pi';himx 


! pass 1 compiler 
! check for bugs 


! pass 2 compiler 
! linker 


$ ! 

$ ! 

$ ! Build the S-record file and clean up the extra files, leaving only 
$ ! the .PAS and .300 files. 

$ ! 

$ xbuild 'pi' 'p2' 'p3' 'p4' 

$ delete 'pi'.11;*, 'pi'.pi;*, 'pl'.ro;*, 'pl'.sr;*, "pi'.pc;* 

$ exit 
$ ! 

$ ! Clean up after compilation errors, leaving the .PL file so the user 
$ ! can find his bugs. 

$ ! 

$ bugs: 

$ write sys$output "Aborted — compilation errors" 

$ delete 'pi'.pc;* 

$ exit 


4. XLINK.COM 
$ ! 

$ ! Motorola 68000 Cross-Linker 
$ ! 

$ ! The linker may be used exactly the same as on the EXORmacs. 

$ ! Note that all files must reside in the directory where the linker 

$ ! is called from, all files must be .RO, and the user must NOT specify 

$ ! the file extension. Also, all output files must be explicitly 
$ ! specified. 

$ ! 

$ open/write il inputline.dat 
$ write il "'"pi"" 

$ close il 
$ ! 

$ ! Now cause cross software execution. 

$ ! 

$ copy xexedir:pascalib.ro pascalib.ro;9999 
$ on error then goto finish 
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$ on control_y then goto finish 
$ assign/user mode sysScommand sys$input 
$ run xexedir:xlink 
$ ! 

$ finish: 

$ delete inputline.dat;* 

$ delete pascalib.ro;9999 
$ delete headerf.dat;* 

$ exit 


5. XNAMES.COM 

$ ! XNAMES.COM — set up logical names and symbols for using cross 
$ ! software. 

$ ! 

$ ! You should execute this command file (as in your LOGIN.COM) before 
$ ! attempting to use the Motorola 68000 cross-software to build 
$ ! user-written functions. 

$ ! 

$ ! 

$ I Define logical names for the actual locations of the cross-software 
$ ! command files and executables. These should be updated during 
$ ! installation as necessary. 

$ ! 

$ assign disk$ias soft:[loosemore.uwf,dist.com] xcomdir 

$ assign disk$ias soft:[loosemore.uwf.dist.exe] xexedir 

$ ! 

$ ! 

$ ! The following aliases allow the Motorola cross-software to be used 
$ ! under VMS exactly as described in the EXORmacs manuals. 

$ ! 

$ xasm 
$ xpas 
$ xpas2 
$ xlink 
$ ! 

$ ! 

$ ! Finally, two more command files to build S-record files ready to 
$ ! download to the PS 300. 

$ ! 

$ xl :== @xcomdir:xl ! compile, link, and build S-record file 

$ xbuild :== ©xcomdir:xbuiId ! build S-record file 
$ exit 


©xcomdir:xasm 
©xcomdir:xpascal 
©xcomdir:xpascal2 
©xcomdir:xlink 


invoke cross-assembler 
invoke cross-compiler, pass 1 
invoke cross-compiler, pass 2 
invoke cross-linker 
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6. XPASCAL.COM 



$ ! 

$ ! Motorola 68000 Pascal Cross-Compiler 
$ I 

$ ! The compiler may be used exactly the same as on the EXORmacs. 

$ ! Note that the source file must reside in the directory where the 
$ ! compiler is called from, the file extension must be .PAS, and the 
$ I user must NOT specify any other file extensions. 

$ ! 

$ open/write il inputline.dat $ write il '*^^pl^” 

$ close il 
$ I 

$ on error then goto finish 
$ on control_y then goto finish 
$ ! 

$ ! Now cause cross software execution. 

$ ! 

$ run xexedir:xpascal 
$ finish: 

$ delete inputline.dat;* 

$ exit 

7. XPASCAL2.COM 


! 

$ ! Motorola 68000 Pascal Cross-Compiler (Phase 2) 

$ ! 

$ ! The compiler may be used exactly the same as on the EXORmacs. 

$ ! Note that the P-code file must reside in the directory where the 
$ ! compiler is called from, the file extension must be .PC, and the 
$ ! user must NOT specify any other file extensions. 

$ ! 

$ open/write il inputline.dat 
$ write il 
$ close il 
$ ! 

$ on error then goto finish 
$ on control_y then goto finish 
$ ! 

$ ! Now cause cross software execution 
$ ! $ run xexedir:xpascal2 
$ finish: 

$ delete inputline.dat;* 

$ exit 
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Using the Command Files on DEC VAX/UNIX 


This appendix describes the files supplied on magnetic tape to users in DEC VAX/UNIX 
environments and provides such a user with information on the use of the files and special 
downloading instructions. The list below is a complete description of the files distributed on the 
magnetic tape to support the User-Written Function facility under DEC VAX/UNIX: 


Example Files: 

bezier.pas 

chcase.pas 

count.pas 

mag.pas 

spiro.pas 

spstruc.pas { USERSTRUC.PAS modified to include Userdatatype } 

E&S-Provided Files to Support User-Written Functions: 

userlink.asm 

userlink.ro 

userstruc.pas 

E&S-Provided Cross-Software Command Files 

xbuild 

xl 

xnames 

Motorola Cross-Software Files (if purchased through E&S) 

uxasm 

uxpascal 

uxpascal2 

uxlink 

pascalib.ro 

asminit.dat 
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Using the Cross-Software on Unix 4.2 BSD 


Before attempting to use the cross-software, users should edit their .cshrc file to “source” 
the file xnames, which defines the necessary aliases and shell variables. This allows the 
assembler, compiler, and linker to be used as described in the EXORMACS manuals. 
(The only exception is that multiple input files should be separated by instead of 
and if options are specified using the entire argument list should be quoted.) 

Before executing any of the commands described below, you should set your working 
directory to the directory containing the source files for the function you wish to compile 
and link. This directory should also contain copies of userstruc.pas and userlink.ro. 
Since Unix is case sensitive, you must remember to use consistent case for filenames. 

As a convenience, a shell script xl has been provided to compile and link a user-written 
function, and produce the S-record file ready to download to the PS 300. All of the 
code must be contained in a single .pas file, and the name of the function is assumed to 
be the name of the file. To invoke this shell script, you should enter a command of the 
form: 

% xl <filename> <number inputs> <number outputs> <stack size> 

If your function contains code from more than one .pas file, or if you wish to include 
routines you have written in assembly language, you will have to follow these steps: 

(1) Compile Pascal source files: 

% xpas <filenaine> 

% xpas2 <filename> 


(2) Assemble assembly-language source files: 
% xasm <filename> 


(3) Link the object files into an S-record file: 

% xlink ^<filenamel>+<filename2>. . .-f-userlink,<filenamel>,<filenamel>;himx^ 

(4) Add the function header line to the S-record file: 

% xbuild <filename> <number inputs> <number outputs> <stack size> 
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Special Software Installation Instructions for DEC VAX/UNIX 

These steps should be taken prior to using the commands files and the cross-software: 

1. You should edit the shell script xnames so that the shell variables $xexedir and 
$xcomdir reflect the actual pathnames of the directories where the cross-software 
executables and shell scripts (respectively) have been installed. 

2. You must also make sure that the files pascalib.ro and asminit.dat can be found in: 

/usr/local/lib/pas68/pascalib.ro and 
/usr/local/lib/pas68/asminit.dat 

respectively. This may be done either by copying the files, or by creating a link to the 
files. 

3. Make sure that all of the files are publicly readable. 


Files Created by the Motorola Cross-Software 


File Description 
<filename>.pas 
<filename>.pc 

<filename>.pl 

<filename>.asm 

<filename>.ls 

<filename>.ro 

<filename>.sr 

<filename>.ll 

<filename>.300 


Contents 
Pascal source file. 

P-code output from pass 1 of the Pascal compiler and input 
to pass 2. 

Listing produced by pass 1 of the Pascal compiler. 
Assembly-language source file. 

Listing file produced by assembler or pass 2 of the Pascal 
compiler. 

Object file output by assembler of pass 2 of the Pascal 
compiler, input to the linker. 

S-record file created by the linker. 

Link map output by the linker. 

S-record file with header information included. 


PS 300 Advanced Programming 


B-3 



Using the Command Files on DEC VAX/UNIX 


DEC VAX/UNIX Command Files 

This section contains the code for the DEC VAX/UNIX command files that are supplied 
on magnetic tape by E&S to support the User-Written Function facility. 

1. xnames 


# xnames — set up names for using 68k cross-software 

# 

# You should "source” this file in your .cshrc file before attempting 

# to use the Motorola 68000 cross-software to build 

# user-written functions 

# 

# 

# Define names for the actual locations of the cross software shell 

# scripts and executables. These should be updated during 

# installation as necessary. 

# 

set xexedir=''loosemor/dist/exe 
set xcomdir=-loosemor/dist/com 
# 

# 

# The following aliases allow the Motorola cross-software to be used under 

# Unix exactly as described in the EXORMACS manuals. 

# The only exceptions are: 

# (1) Multiple input files should be separated with a instead of "/". 

# (2) If you specify options using "; , the entire parameter list should 

# be enclosed in quotes. 

# 

alias xasm $xexedir/uxasm 

alias xlink $xexedir/uxlink 

alias xpas $xexedir/uxpascal 

alias xpas2 $xexedir/uxpascal2 

# 

# 

# Finally, two more command files to build S-record files ready to 

# download to the PS 300: 

# 

alias xl csh $xcomdir/xl 

alias xbuild csh $xcomdir/xbuild 
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2. xl 

# xl — compile and link user-written functions, producing S-record file 

# 

# This shell script compiles and links a user-written function, producing 

# an S-record file ready for downloading to the PS\300. The function 

# must be contained in a single Pascal source file; the name of the 

# function is the name of the source file. An extension of .pas is 

# assumed for the input file, and an extension of .300 for the output 

# S-record file. 

# You should execute this shell script out of the directory containing the 

# Pascal source file for the user-written function. 

# 

# Parameters: 

# $1 = name of UWF 

# $2 = number of inputs 

# $3 = number of outputs 

# $4 = estimated stack size 

# 

# 

# Get the name of the function (required). 

# 

if ($#argv > 0) then 
set name=$l 

else 

echo -n ^Name of UWF: ' 
set name=($<) 

endif 

# 

# 

# Compile and link the UWF, using Motorola 68000 cross-software. We can 

# detect compilation errors by checking for a 0-length .pc file. 

# 

xpas $name 

set pclen='ls -1 $name.pc | awk '{ print $4 
if ($pclen == 0) goto bugs 
xpas2 $name 

xlink ”$name+userlink,$name,$name;himx” 

# 

# 

# Build the S-record file and clean up the extra files, leaving only the 

# .pas and the .300 files. 

# 

xbuild $name $2 $3 $4 

rm $name.ll $name.pl Sname.ro $name.sr $name.pc 
exit 
# 
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# w 

# Clean up after compilation errors, leaving the .pi file so the user 

# can find his bugs. 

# 

bugs: echo ^Aborted — compilation errors^ 

rm $name.pc 

exit 


3. xbuild 


# xbuild — build S~record .300 file for a UWF 

# 


# This command file builds an S-record file for a UWF which is ready to 

# download to the PS 300. The header information is found and added to 

# the front of the output file from the linker. 

# You should execute this shell script from the directory containing the 

# files for the UWF. The name of the UWF is assumed to be the same as 

# the name of the files. The .11 and the .sr files produced by the 

# linker must be present. An extension of .300 is used.for the output 

# file. 

# Parameters: 

# $1 = name of UWF 

# $2 = number of function inputs 

# $3 = number of function outputs 

# $4 « estimated stack size 

# 


# Ask the user for parameters if none were supplied. 

# 

if ($#argv > 0) then 
set name=$l 
else 

echo -n ^Name of UWF: ^ 
set name=($<) 
end if 

if ($#argv > 1) then 
set inputs=$2 else 

echo -n 'Number of function inputs: ' 
set inputs==($<) 
end if 

if ($#argv > 2) then 
set outputs=$3 
else 

echo -n 'Number of function outputs: ' 
set outputs=($<) 
endif 

if ($#argv > 3) then 
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set stacksize=$4 
else 

echo -n ^Estimated stack size: ^ 
set stacksize=($<) 
end if 
# 

# 

# Determine the length of the code produced. This is found in the link 

# map (the .11 file). 

# set len='awk '/Total Length/ { print $4 }' Sname.ll' 

# 

# 

# Write the ,300 file. This involves putting together the header line and 

# appending a semicolon to the end of the file. 

# 

echo $len $name $inputs $outputs Sstacksize >$name.300 

cat $name. sr »$name.300 

echo ';' »$name. 300 

echo $name.300 created 

exit 
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Using the Cross-Software on IBM VM/SP 


This appendix describes the files supplied on magnetic tape to users in IBM VM/SP environments 
and provides such a user with information on the use of the Motorola cross-software. The list 
below is a complete description of the files distributed on the magnetic tape to support the 
User-Written Function facility imder IBM VM/SP: 


Example Files: 

BEZIER PASCAL 
CHCASE PASCAL 
COUNT PASCAL 
MAG PASCAL 
SPIRO PASCAL 

SPSTRUC PASCAL { USERSTRUC.PAS modified to include Userdatatype } 


E&S-Provided Files to Support User-Written Functions: 

USERLINK ASSEMBLE 
USERLINK OBJECT 
USERSTRU PASCAL 


Motorola Cross-Software Files (if purchased through Ei5^!) 

ASMB MODULE 
PASCALCO MODULE 
DIRECT MODULE 
LINK MODULE 
PASCALIB DATA 
ASMINIT DATA 


How To Use the Cross-Software on IBM VM/SP 

It is very important that you are familiar with the following information before you try to 
use the Motorola cross-software. Because of the nature of the IBM environment, explicit 
files that call the cross-software are not provided by E&S. Use the following information 
to create the S-record file that contains the code for your user-written function, correctly 
format the file for downloading, and download it to the PS 300. 
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Pascal Differences 


The IBM version of the Motorola Pascal cross-compiler uses different lexical conventions 
than standard Pascal. In particular, you should: 

• use @ instead of t for pointer references 

• use (. and .) instead of [ ] for array references. 

You cannot refer to files by name explicitly in $F=<filename> statements. To include files 
during compilation, the $F statement should refer to a DDNAME. You must include a 
FILEDEF command to define that DDNAME prior to invoking the cross-compiler. 


Using the Cross-Compiler 


Before invoking the cross-compiler, you must execute a number of FILEDEF commands 
to define the files used. These files are: 


SOURCE 

LISTING 

PCODE 

OUTPUT 

P2LIST 

FILEl 

FILE2 


The file containing the Pascal source code to be compiled. 
This file is read in by pass 1 of the compiler. 

The listing output by pass 1 of the compiler. 

This file contains the intermediate code produced by pass 1 
of the compiler and used as input by pass 2. 

Both passes of the compiler write results of the compilation 
to the file OUTPUT, which is normally associated with the 
terminal. 

The listing file output by pass 2 of the compiler. 

Pass 2 writes the relocatable object module to this file. 

This is a temporary file used by pass 2 of the compiler. 


In addition, if you have referenced any files to be included via $F statements in your 
Pascal source file, you must also execute FILEDEF commands for these files. 

The following exec file, UWFPASC EXEC, will compile the Pascal source file input as the 
first parameter. It is assumed that the source file includes USERSTRU PASCAL through 
a statement of the form: 

{$F=INCLUDE } 

FILE: UWFPASC EXEC 

&TRACE ERR 
^CONTROL &OFF 
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FILEDEF * CLEAR 

FILEDEF OUTPUT TERMINAL (RECFM F LRECL 80 BLOCK 80 
FILEDEF SOURCE DISK &1 PASCAL A 
FILEDEF INCLUDE DISK USERSTRUC PASCAL A 

FILEDEF LISTING DISK LISTING A (RECFM VBA LRECL 133 BLOCK 3990 
FILEDEF PCODE DISK PASCPCOD DATA A (RECFM VB LRECL 256 BLOCK 2600 
FILEDEF P2LIST DISK kl DATA A (RECFM VBA LRECL 133 BLOCK 3990 
FILEDEF FILEl DISK kl OBJECT A (RECFM FB LRECL 256 BLOCK 2560 
FILEDEF FILE2 DISK PASCFIL2 DATA (RECFM FB LRECL 256 BLOCK 2560 
PASCALCO 
DIRECT 
EXIT 

After invoking the cross-compiler, you should check the LISTING file for errors. 


Using the Cross-Assembler 




The cross assembler requires that you execute FILEDEF statements to define the 
following DDNAMES: 

OUTPUT 

SOURCE 

LISTING 

OBJECT 

INITFILE 

The following exec file, MYASMY EXEC, will assemble the source file passed as 
parameter 1: 


Normally, this file is allocated to the terminal. 

This should be allocated to the assembly source input file. 

The cross assembler will write its output listing to this file. 

The object code output by the assembler will be written to 
this file. 

The initialization file, which must be read in at the beginning 
of each invocation of the cross-assembler. 


FILE: MYASMY EXEC 


k TRACE ON 
k CONTROL &0FF 
FILEDEF * CLEAR 
FILEDEF OUTPUT TERMINAL 

FILEDEF SOURCE DISK kl ASSEMBLE * (RECFM FB LRECL 80 BLOCK 3200 
FILEDEF LISTING DISK kl LISTING » (RECFM VB LRECL 133 BLOCK 3990 
FILEDEF OBJECT DISK kl OBJECT * (RECFM FB LRECL 256 BLOCK 2560 
FILEDEF INITFILE DISK ASMINIT DATA Cl (RECFM FB LRECL 80 BLOCK 3200 
ASMB 
k EXIT 
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Linking 



Before invoking the linker, you should execute FILEDEF statements to define the 
following files: 

INPUT The file containing the linker commands. This may be 

assigned to the terminal. 

OUTPUT The map file output by the Knker. 


OUTFIT 

HEADERF 

PASCALIB 


The load module produced as output by the linker. 

A temporary file used by the linker for processing the H 
option. 

The default run-time library for Pascal object modules. 


In addition, you must execute a FILEDEF for each object file you wish to input to the 
linker. These are referenced by the file INPUT, which should contain commands of the 
form: 

INPUT <ddnamel> 

INPUT <ddname2> 




END 

For example, the file LINK TXT contains the following commands: 

INPUT OBJl 
INPUT 0BJ2 
END 

This file is referenced by UWFLINK EXEC. This exec file takes the name of a single 
object file as a parameter, and links it with USERLINK OBJECT. 

FILE: UWFLINK EXEC 

&TRACE ON 
^CONTROL &OFF 
FILEDEF * CLEAR 

FILEDEF INPUT DISK LINK TXT A (RECFM F LRECL 80 BLOCK 80 
FILEDEF OUTPUT DISK MAP A (RECFM F LRECL 80 BLOCK 80 
FILEDEF OUTFIL DISK &1 LOAD A (RECFM VB LRECL 256 BLOCK 2600 
FILEDEF HEADERF DISK M68KHDRF DATA C (REDFM F LRECL 80. BLOCK 80 
FI OBJl DISK kl OBJECT A (RECRM FM LRECL 256 BLOCK 2560 
FI OBJ2 DISK USERLINK OBJECT A (RECFM FB LRECL 256 BLOCK 2560 
FILEDEF PASCALIB DISK PASCALIB DATA Cl 
DESBUF 
LINK 



^ ■ 
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Modifying the S-Record File 


Before you can download the S-record file for the UWF to the PS 300, you must modify 
it to contain a header line of the format described in Appendix G, and terminate the file 
with a semicolon. 

You should examine the map file output by the linker to determine the length of code for 
including in the header line. 


Downloading the UWF to the PS 300 



The following is an example of a command file to run the program SRecsnd that sends the 
specified file to the PS 300 (this requires the file name as a parameter): 

&TRACE ON 

&CONTROL &OFF 

EXEC P6P FILEDEF * CLEAR 

FILEDEF INPUT TERMINAL 

FILEDEF OUTPUT TERMINAL 

FILEDEF SRECFILE DISK LOAD A (RECFM VB LRECL 256 BLOCK 2600 
LOAD SRECSND (START 

This is an example of the Pascal program, SRecsnd, that sends a file to PS 300. This 
program makes calls to the PS 300 GSR routines. 


FILE: SRECSND PASCAL * 

program srecsnd (input, output, srecfile ); 
CONST 

%INCLUDE PROCONST 
TYPE 

%INCLUDE PROTYPES 
VAR 

Ssrecfile ; text; 
istr : string ( 256 ); 

crlfa : packed array (. 1..2 .) of char; 
crlf : string( 2 ); 

%INCLUDE PROEXTRN 

PROCEDURE err ( errnum : integer ); 

BEGIN 

writeln( ^ got error: errnum ); 
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BEGIN 

pattach( "junk', err ); 
reset( srecfile ); 
crlfa (. 1 .) := CHAR ( 13 ); 

crlf := STR( crlfa ); 
pmuxg ( 7, err ); 

WHILE NOT EOF (srecfile) DO 

BEGIN readln (srecfile, istr ); 
Pputgx (istr, err ); 

Pputgx (crlf, err ); 

END; 

writeln; 

PDetach ( err ) ; 

END. 
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Using the Command Files on IBM MVS/TSO 


The list below is a complete description of the files distributed on the magnetic tape to support the 
User-Written Function facility under IBM MVS/TSO: 

Example Files: 

BEZIER PASCAL 
CHCASE PASCAL 
COUNT PASCAL 
MAG PASCAL 
SPIRO PASCAL 

SPSTRUC PASCAL { USERSTRUC.PAS modified to include Userdatatype } 

E&S-Provided Files to Support User-Written Functions: 

USERLINK ASSEMBLE 
USERLINK OBJECT 
USERSTRU PASCAL 


Motorola Cross-Software Files (if purchased through E&S) 


ASMB MODULE 
PASCALCO MODULE 
DIRECT MODULE 
LINK MODULE 
PASCALIB DATA 
ASMINIT DATA 


The MVS/TSO user should refer to the Motorola manuals distributed with the Motorola 
cross-software for instructions on the use of the crosscompiler, cross-assembler, and 
cross-linker. 



For information on preparing the file for downloading, and for downloading it to the 
PS 300, refer to the sections entitled “Modifying the S-Record File” and “Downloading 
the UWF to the PS 300” in Appendix C of this manual. 
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APPENDIX E 
USERSTRUC.PAS 


This appendix contains the examples and supplied command files from the USERSTRUC.PAS 
file, that is distributed on magnetic tape. Reference to this file is made throughout the document 
and it is provided here for completeness. 



CONST MaxinputQueues = 127; { Max #of input queues for a function } 

TYPE Intl6 = -32768..32767; { 16-bit integer } 

Int8 = -128..127; { 8-bit integer } 

Ptrqdata = fQdata ; { pointer to a message } 

PtrUWFInQarray = ^IMFlnQarray; 

UWFInQarray = Array [1..MaxInputQueues] of PtrQdata; 

InUWFQarray = UWFInQarray; {for compatibility with older versions} 


double = 


RECORD 


c: Intl6; 

m: integer; 

notused: intl6; 

END; 

PS 300_floating_point = 


{ 16 bit biased binary exponent} 

{ 32 bit floating point fraction} 

{ waste, to make = 8 bytes for} 

{ faster array indexing} 
double; { old name, for compatibility} 


Vector = ARRAY [ 0..3 ] OF double; 

Matrix = ARRAY [ 0..3 , 0..3 ] OF double; 


Bytespell = ARRAY [ 1..255 ] OF char; 

Qdtype = { types of Qdata (message) blocks } 

( 

{ 0} Qreset, { dataless: reset a function instance } 


{ 1} Qprompt, { dataless: flush the Cl pipeline } 
{ 2} Qboolean, { normal carrier of boolean values } 
{ 3} Qinteger, { normal carrier of integer values } 
{ 4} Qreal, { normal carrier of floating point values} 
{ 5} Qstring, { original carrier of byte strings } 
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{ 6 } 
{ 7 } 


{ 8 } 
{ 9 } 
{ 10 } 
{ 11 } 
( 12 ) 
{13} 
{14} 
{15} 
{16} 
{17} 
{18} 
{19} 
{ 20 } 


Qpacket, { new carrier of byte strings } 

Qmorepacket, { alternate to Qpacket (with the distinction } 
{ making a difference only on the link } 

{ between F:DEPACKEt and F:DEMUX/F:CIROUTE).} 
{ 2D vector including P bit } 

{ 2D vector including L bit } 

{ 2D vector with no P/L bit (normal vector) } 

{ 3D vector including P bit } 

{ 3D vector including L bit } 

{ 3D vector with no P/L bit (normal vector) } 

{ 4D vector including P bit } 

{ 4D vector including L bit } 

{ 4D vector with no P/L bit (normal vector) } 

2x2 matrix } 


Qmove2, 
Qdraw2, 
Qvec2, 
Qmove3, 
Qdraw3, 
Qvec3, 
Qmove4, 
Qdraw4, 
Qvec4, 
Qmat2, 
Qmat3, 
Qmat4, 
Qusertype 


3x3 matrix } 

4x4 matrix } 

{ type which user may use 


to define own message } 


{ padding 

, to 

make 

the field 

16-bi 

t, as 

it is in the full system } 

Pad, 

Pae, 

Paf, 

Pag, 

Pah, 

Pai, 

Paj , 

Pak, 

Pal, 

Pam, 

Pbd, 

Pbe, 

Pbf, 

Pbg, 

Pbh, 

Pbi, 

Pbj , 

Pbk, 

Pbl, 

Pbm, 

Pcd, 

Pee, 

Pcf, 

Peg, 

Pch, 

Pci, 

Pej, 

Pek, 

Pci, 

Pem, 

Pdd, 

Pde, 

Pdf, 

Pdg, 

Pdh, 

Pdi, 

Pdj, 

Pdk, 

Pdl, 

Pdm, 

Ped, 

Pee, 

Pef, 

Peg, 

Peh, 

Pei, 

Pej, 

Pek, 

Pel, 

Pem, 

Pfd, 

Pfe, 

Pff, 

Pfg, 

Pfh, 

Pfi. 

Pfj. 

Pfk, 

Pfl, 

Pfm, 

Pgd, 

Pge, 

Pgf, 

Pgg. 

Pgh, 

Pgi, 

Pgj, 

Pgk, 

Pgl, 

Pgm, 

Phd, 

Phe, 

Phf, 

Pbg, 

Phh, 

Phi, 

Pbj , 

Phk, 

Phi, 

Phm, 

Pid, 

Pie, 

Pif, 

Pig, 

Pih, 

Pii, 

Pij , 

Pik, 

Pil, 

Pirn, 

Pjd, 

Pje, 

Pjf, 

Pjg. 

Pjh, 

Pji. 

Pjj. 

Pjk, 

Pjl, 

Pjm, 

Pkd, 

Pke, 

Pkf, 

Pkg, 

Pkh, 

Pki, 

Pkj, 

Pkk', 

Pkl, 

Pkm, 

Pld, 

Pie, 

Plf, 

Pig, 

Plh, 

Pli, 

Plj. 

Plk, 

Pll. 

Plm, 

Pmd, 

Pme, 

Pmf, 

Pmg, 

Pmh, 

Pmi, 

Pm j , 

Pmk, 

Pml, 

Pmm, 

Pnd, 

Pne, 

Pnf, 

Png, 

Pnh, 

Pni, 

Pnj , 

Pnk, 

Pnl, 

Pnm, 

Pod, 

Poe, 

Pof, 

Peg, 

Poh, 

Poi, 

Poj , 

Pok, 

Pol, 

Pom, 

Ppd, 

Ppe, 

Ppf, 

Ppg, 

Pph, 

Ppi, 

Ppj, 

Ppk, 

Ppl, 

Ppm, 

Pqd, 

Pqe, 

Pqf, 

Pqg, 

Pqh, 

Pqi, 

Pqj, 

Pqk, 

Pql, 

Pqm, 

Prd, 

Pre, 

Prf, 

Prg, 

Prh, 

Pri, 

Prj, 

Prk, 

Prl, 

Prm, 

Psd, 

Pse, 

Psf, 

Psg, 

Psh, 

Psi, 

Ps j, 

Psk, 

Psl, 

Psm, 

Ptd, 

Pte, 

Ptf, 

Ptg, 

Pth, 

Pti, 

Ptj, 

Ptk, 

Ptl, 

Ptm, 

Pud, 

Pue, 

Puf, 

Pug, 

Puh, 

Pui, 

Puj , 

Puk, 

Pul, 

Pum, 

Pvd, 

Pve, 

Pvf, 

Pvg, 

Pvh, 

Pvi, 

Pvj , 

Pvk, 

Pvl, 

Pvm, 

Pwd, 

Pwe, 

Pwf, 

Pwg, 

Pwh, 

Pwi, 

Pw j , 

Pwk, 

Pwl, 

Pwm, 

Pxd, 

Pxe, 

Pxf, 

Pxg, 

Pxh, 

Pxi, 

Pxj , 

Pxk, 

Pxl, 

Pxm, 

Pyd, 

Pye, 

Pyf, 

Pyg, 

Pyh, 

Pyi, 

Pyj, 

Pyk, 

Pyl. 

Pym, 

Pzd, 

Pze, 

Pzf, 

Pzg, 

Pzh, 

Pzi, 

Pzj, 

Pzk, 

Pzl, 

Pzm 


) : 
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{ TYPE declarations continued } 

Qdata = 

RECORD 

Next: Ptrqdata ; { next message in a list of messages } 

CASE Qtyp: Qdtype OF { type of message } 

{ Qreset: no datum carried } 

• { Qprompt: no datum carried } 

Qboolean: 

( 

b: boolean 
) ; 

Qinteger: 

( 

i: integer 

) ; 

Qreal: 

( 

r: double 

) ; 

Qstring: { an old form of byte-string message } 

( 

1: intl6 ; { # bytes of message } 

Qs_pad: intl6 ; { padding ... aligns with Qpacket } 

n: Bytespell { bytes of message } 

) ; 

Qpacket, Qmorepacket: { newer form of byte-string } 

( 

P_lth: intl6 ; { max byte number } 

P_beg: intl6 ; { min byte number } 

P_cnt: Bytespell { bytes of message } 

) ; 

Qmove2, Qdraw2, Qvec2, 

QmoveS, QdrawS, QvecS, 

Qmove4, Qdraw4, Qvec4: 

( 

V4: Vector { all vectors use 4D indexing } 

) ; 

Qmat2, QmatS, Qmat4: 

( 

Mat4: Matrix { all matrices use 4x4 indexing } 

) ; 

END ; { Qdata } 

{ ***♦ Note: there are no global VARs available **** } 
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FUNCTION CkPrivate : Ptrqdata; 

FORWARD ; 

PROCEDURE SavePrivate ( msg : Ptrqdata ); 

FORWARD ; 

FUNCTION Ckinputs ( first, last : Intl6 ) : PtrUWFInQarray; 
FORWARD ; 

FUNCTION Cleaninputs : BOOLEAN; 

FORWARD ; 

PROCEDURE SendMsg ( VAR msg : Ptrqdata; outport : Intl6 ); 
FORWARD ; 

PROCEDURE QSendCopyMsg ( source, destination : Intl6 ); 
FORWARD ; 

PROCEDURE QIllMessage ( input : Intl6 ); 

FORWARD ; 

PROCEDURE QlllValue ( input : Intl6 ); 

FORWARD ; 

PROCEDURE Qincompatmsgs ( one : Intl6; theother : Intl6 ); 
FORWARD ; 

FUNCTION Msgcopy(m: Ptrqdata): Ptrqdata ; 

FORWARD ; 

PROCEDURE Dropinessage(VAR m: Ptrqdata) ; 

FORWARD ; 

PROCEDURE Systemerror(n: Intl6) ; 

FORWARD ; 

FUNCTION Fpecomp(VAR X1,X2: double): Int8 ; 

FORWARD ; 

PROCEDURE Fpabs(VAR r: double) ; 

FORWARD ; 

PROCEDURE FCadd(VAR Augend, Addend: double; 

VAR Sum: double) ; 

FORWARD ; 

PROCEDURE FCsubtract(VAR Minuend, Subtrahend: double; 

VAR Difference: double) ; 

FORWARD ; 

PROCEDURE FCmultiply(VAR a, b: double; 

VAR Product: double) ; 

FORWARD ; 

PROCEDURE FCp2multiply(VAR Innum: double; Power: integer; 

VAR Outnum: double) ; 

FORWARD ; 

PROCEDURE FCdivide(VAR Dividend, Divisor: double; 

VAR Quotient: double) ; 

FORWARD ; 

PROCEDURE FCint2double( num : Integer; VAR Floated: douhlf^) ; 
FORWARD ; 
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PROCEDURE FCround(VAR Innum: double; VAR Outnum: integer) ; 

FORWARD ; 

PROCEDURE FCinteger(VAR Innum: double; VAR Outnum: integer) ; 

FORWARD ; 

FUNCTION FCnearzero ( VAR tiny : double; negpower2 : intl6 

) : int8 ; { negpower2=l —> within .5; =2 —> within} 

{ .25 } 

FORWARD ; • 

PROCEDURE FCsqroot(VAR a: double; 

VAR Sqroot: double) ; 

FORWARD ; 

PROCEDURE Sincos(Angle: integer; VAR Sine: double; 

VAR Cosine: double) ; 

FORWARD ; 

FUNCTION Rndmnumber(seed : Integer): Intl6; 

FORWARD ; 

FUNCTION Newqpacket( Typ: Qdtype; a Qpacket or Qmorepacket a 
Nbytes: Intl6): Ptrqdata ; 

FORWARD ; 

FUNCTION Newqreal: Ptrqdata ; 

FORWARD ; 

FUNCTION Newqinteger: Ptrqdata ; 

FORWARD ; 

FUNCTION Newqboolean: Ptrqdata ; 

FORWARD ; 

FUNCTION NewqniKTyp: Qdtype): Ptrqdata ; { Qreset; Qprompt } 

FORWARD ; 

FUNCTION Newqvector(Typ: Qdtype): Ptrqdata ; { Qvec2, ... } 

FORWARD ; 

FUNCTION Newqmatrix(Typ: Qdtype): Ptrqdata ; { Qmat2, ... } 

FORWARD ; 

FUNCTION Vfetch( Name: Ptrqdata) : Ptrqdata; { a Qpacket } 

FORWARD ; 

PROCEDURE Vstore( Name: Ptrqdata; VAR New_val: Ptrqdata) ; 

FORWARD ; 

FUNCTION My__name : Ptrqdata ; 

FORWARD ; 

PROCEDURE My_in_out ( VAR N__in,N_out: intl6 0 ; 

FORWARD ; 

FUNCTION Tioks: integer ; 

FORWARD ; 

FUNCTION Csecs: integer ; 

FORWARD ; 

FUNCTION Frames: integer ; 


PS 300 Advanced Programming 


E-5 




USERSTRUC,PAS 


FORWARD ; 

PROCEDURE HrtimeCVAR c,f,d: integer) ; 

FORWARD ; 

PROCEDURE Char_text(c: char; VAR b,e: Intl6; VAR Ca: Bytespell) ; 
FORWARD ; 

PROCEDURE Text_text(VAR B1,E1: Intl6; VAR Cal: Bytespell; 

VAR B2.E2: Intl6;*VAR Ca2: Bytespell) ; 

FORWARD ; 

PROCEDURE Int__text(n: integer; Ns,Nz: Intl6; 

VAR b,e: Intl6; VAR Ca: Bytespell) ; 

FORWARD ; 

PROCEDURE Time_text(n: integer; VAR b,e: Intl6; VAR Ca: Bytespell) ; 
FORWARD ; 

PROCEDURE Real_text(VAR r: double; VAR b,e: Intl6; VAR Ca: Bytespell) 
FORWARD ; 

FUNCTION NewTry ( num_bytes : INTEGER ) : Ptrqdata; 

FORWARD; 

PROCEDURE UWFerror (VAR msg : Ptrqdata ); 

FORWARD; 

PROCEDURE Set__Cness( input : Intl6; cqtype: Boolean ); 

FORWARD; 


Advanced UWF Procedures 

FUNCTION Lk_cursuiffix ( Nlth: integer; VAR Nspell: Namespell) : 
Ptralphablk; 

FORWARD; 

FUNCTION Lk_nosuffix ( length: Integer; Cinum: Int 8; suffix: Char; 
VAR Nspell-.Namespell) : Ptralphablk; 

FORWARD; 

PROCEDURE Lgaupdate ( Name: Ptralphablk; data: Ptrnamedentity; 

VAR Uph,Upt: Ptravuplbk); 

FORWARD; 

PROCEDURE Announceupdate ( VAR Uph,Upt: Ptravupblk); 

FORWARD; 

PROCEDURE Msgstore ( VAR Uph.Upt: Ptravupblk); 

FORWARD; 

PROCEDURE Msgstore ( Msg: Ptrqdata; a: Ptralphablk; n: integer); 

. FORWARD; 

PROCEDURE Setlock ( VAR x: Lock); 

FORWARD; 

PROCEDURE Clrlock ( VAR s: Lock); 

FORWARD; 
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PROCEDURE Incausage ( a: Ptralphablk); 

FORWARD; 

PROCEDURE Decausage ( a: Ptralphablk); 

FORWARD; 

PROCEDURE AcpProof ( VAR location: ptracpcblk; newval: ptracpcblk); 
FORWARD; 

PROCEDURE Acpprfl ( VAR location: ptrsavstate; value: ptrsavstate); 
FORWARD; 

PROCEDURE OLbaddtoset ( A_son: Ptralphablk; A__father: Ptralphablk; 

VAR Uph,Upat: Ptravupblk; VAR Error: boolean; Optimize : boolean); 


FORWARD; 

PROCEDURE Removefromset ( A_father: Ptralphablk; A__son: Ptralphablk; 
VAR Uph,Upt: Ptravupblk; VAR Error: boolean); 

FORWARD; 

FUNCTION FetchBlock ( block: PtrNamedentity; Upt: Ptravupblk): 

Ptrnamedentity; 


FORWARD; 

PROCEDURE Acp_v3f 
FORWARD; 

PROCEDURE Acp_v2f 
FORWARD; 

PROCEDURE Acp_v3b 
Intl6); 
FORWARD; 

PROCEDURE Acp_v2b 
Intl6); 
FORWARD; 


( VAR v: Vector; 
( VAR v: Vector; 
( VAR v: Vector; 

( VAR v: Vector; 


VAR acpv: Vec3f; 
VAR acpv: Vec2f; 
VAR acpv: Vec3b; 

VAR acpv: Vec2b; 


PROCEDURE NStoreVector ( VAR block: Ptrnamedentity; 
boolean firstblock: Ptrnamedientity); 


pi: boolean); 
pi: boolean); 
pi: boolean; exp: 

pi: boolean; exp: 

VAR v: Vector; pi: 


FORWARD; 

FUNCTION nNewAcpdata ( n: intl6; t: Dattype): Ptrnamedentity; 
FORWARD; 

PROCEDURE Store3x3 ( VAR m: Matrix3; Ob: Ptrnamedentity; n: intl6); 


. FORWARD; 

PROCEDURE Store4x4 ( VAR m: Matrix4; Ob: Ptrnamedentity; n: intl6); 
FORWARD; 

PROCEDURE Drop_name ( a: Ptralphablk); 

FORWARD; 

PROCEDURE GetVector ( block: Ptrnamedentity; index: Intl6; 

VAR v: Vector; VAR pi: Boolean); 

FORWARD; 

PROCEDURE Rawbacopy ( Nbytes: intl6; VAR Inba.Outba: intS); 

FORWARD; 

PROCEDURE Rawcbcopy (* Nbytes: intl6; VAR Inba:char; VAR Outba: intS); 
FORWARD; 

PROCEDURE Rawchcopy ( Nbytes: intl6; VAR Inba,Outba: char); 

FORWARD; 
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FUNCTION Size_of ( b: Ptrnamedentity): integer; 

FORWARD; 

FUNCTION FetchAdnum ( f: Ptrnamedentity; upt: Ptravupblk): Intl6; 

FORWARD; 

FUNCTION nFetchCopy ( block: PtrNamedentity; start: Intl6; count: Intl6; 
upt: Ptravupblk) : PtrNamedentity; 

FORWARD; 

PROCEDURE WaitFrame ( framecnt : integer); 

FORWARD; 

FUNCTION loc_chead : Ptrcommhead; 

FORWARD; 

FUNCTION ptr_dcb : Ptrdcb; 

FORWARD; 

PROCEDURE DropNE ( f: Ptrnamedentity); 

FORWARD; 

PROCEDURE Newreturns ( givemenil : boolean); 

FORWARD; 

PROCEDURE Reactivate ; 

FORWARD; 

FUNCTION Myanyoutputs ( n: int8): Boolean; 

FORWARD; 

PROCEDURE Pushmyinput ( m: Ptrqdata; n: Int8); 

FORWARD; 

PROCEDURE WaitCsec ( cseccnt : integer); 

FORWARD; 





E-8 


PS 300 Advanced Programming 



APPENDIX F 


t 

Function Header Line Format 


This appendix contains a description of the function header line format used to name a function, 
define the number of inputs and outputs, and provide the stack usage. 

The function-naming command must use the following syntax: 



<length> <function_name> <number inputs> <number outputs> <stack size> 
where: 

<lerigth> is the number of bytes in decimal of the file (the number of bytes can be found in 
the linker listing labeled Total Length*). 

<function_name> is the PS 300 name for the user-written function. 

<nuinber inputs> is the number of input queues of the user-written function. 

<number outputs> is the number of output ports of the user-written function. 

<stack size> is the estimated total stack usage requirements in decimal. (Refer to the 
Reference Section for estimates of stack usage of procedures.) 

These parameters are delimited by spaces. 
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S-Record Format 


The S-record format for modules was devised for the purpose of encoding programs or data files 
for transportation between computer systems. In an S-record, a two-level encoding method is 
used to transform each byte of binary data into two printable characters; therefore, the 
transportation process can be visually monitored and the file data can be more easily edited. 

When viewed by the user, S-records are essentially character strings made up of several fields, in 
which pairs of characters are interpreted as hexadecimal values from 1- to 2-byte length, 
representing a count, an address, a data record, or a checksum. Internally, each record is viewed 
as a sequence of byte values representing characters. To be compatible with teletype units, 
S-records may be no longer than 70 bytes. Since 10 bytes are required in each record for the 
type, byte, count, address, and checksum fields, the variable-length data field may be allocated at 
maximum 60 bytes. This translates to 60 characters or 30 character pairs or bytes of data per 
record, from the user viewpoint. 

The internal format of an S-record comprises five fields, as shown below: 


type 

byte_count 

address 

data 

checksum 


where the fields are composed as follows: 


Field Size (bytes) Contents 


type 


2 Record type—SO, SI, S2, or S9. The two bytes are 

hexadecimal, encoded directly from byte values. 


byte count 2 The count of the character pairs in the record, excluding 

the type and checksum fields. The high and low order 
hexadecimal digits of the actual byte value are 
individually represented as two hexadecimal bytes in the 
S-record. 
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Field Size (bytes) Contents 


address 4-6 The address at which the data field is to be loaded into 

memory. The high and low order hexadecimal digits of 
each actual type value are individually represented as 
hexadecimal bytes in the S-record. 

data 0-60 Memory loadable data or descriptive information. High 

and low order hexadecimal digits of successive, actual 
byte values are individually represented as hexadecimal 
bytes in the S-record. 


checksum 2 The least significant byte of the one’s complement of the 

sum of the values represented by the pairs of characters 
making up the byte count, the address, and the data 
fields. The high and low order hexadecimal digits of the 
actual checksum value are individually represented as 
two hexadecimal bytes in the S-record. 


Data blocks output by the linker may contain S-records of the following types: 

SO The header record for each block of data. Subfields in the data field may be: 

module name = 20 bytes 
version number = 2 bytes 
revision number = 2 bytes 
description = 0 to 36 bytes 

Each of the subfieids is composed of bytes, whose associated character, when 
paired, represent 1-byte hexadecimal values in the case of the version and 
revision numbers, or represent the encodement of the module name and 
description specified by the user with the interactive IDENT command. 

51 A record containing data and the 3-byte address at which the data are to 
reside. 

52 A record containing data and the 3-byte address at which the data are to 
reside. 

S9 A termination record for a block of S-records. The address field may 
optionally contain the address, specified by the user with the ENTRY 
command, to which control is to be passed. If not specified, the first entry 
point specification encountered in the object module input will be used. There 
is no data field. 
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Motorola Pascal Register Usage 


This appendix contains a description of the Pascal register usage and calling conventions and 
includes descriptions of procedures to be followed when linking more than one procedure or using 
assembly language files. 

An assembly language routine may be called externally by a Pascal program using normal Pascal 
argument passing. Such a routine may: 

• Perform a function not available in Pascal; i.e., data manipulation or I/O not 
provided in the applicable library, or some mathematics not supported by Pascal. 

• Optimize code to be used repetitively in a real-time environment. The Pascal 
compiler does optimize, but a user-written assembly language routine may be shorter 
and faster. 


Program Preparation 

There are two requirements that must be satisfied to include an assembly language 
subroutine in a Pascal program. First, the external assembly language routine must be 
declared in the Pascal program. This is done by declaring a level 1 procedure or function 
(i.e., one contained only by the main program) using the forward directive. A good place 
for these declarations is prior to the first nonextemal heading. 

For example: 

FUNCTION MSGCOPY(m:Ptrqdata):Ptrqdata; 

FORWARD; 


The external assembly language subroutine may then be called just as any Pascal 
procedure or function. The second requirement concerns the file that contains the 
assembly language routine. This file must have an entry point, that has been declared 
external with an XDEF, with the same name as the procedtire of function in the Pascal 
program. The assembler must be informed that the subroutine is to be included in section 
9. A ’SECTION 9* directive at the beginning of the assembly language subroutine file 
accomplishes this. 
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Calling a Routine 


Calling an assembly language routine is identical in format (and its run-time requirements 
are identical in system usage) to a regular function or procedure call in Pascal. 
Parameters, for example, are placed on the top of the stack, beneath the return address, 
in the order they are declared; the first parameter is stacked first and the last parameter is 
nearest the top of the stack. If the assembly language routine is declared a function, the 
space for the return value is below the first parameter on the stack (i.e., the address 
contained in A7 plus a positive displacement). For example, given the declaration and 
call in the following Pascal program fragment: 

FUNCTION SUMTHREE(I,J,K:INTEGER):INTEGER; FORWARD; 

BEGIN 

A:= SUMTHREE(3,5,7); 

jthe stack would look as follows upon entry to the assembly language subroutine named 
Sumthree: 


Top of Stack (A7)- 


POSITIVE 
OFFSETS 
FROM A7 




RETURN ADDRESS 
4 bytes 


FORMAL PARAMETER 
K; 4 bytes; 

_ value = 7 _ 

FORMAL PARAMETER 
J; 4 bytes 

_ value s 5 _ 

FORMAL PARAMETER 
I; 4 bytes 

_ value = 3 _ 

FUNCTION VALUE 
SUMTHREE: 4 bytes; 
value is undefined 


low address 


high address 


The size of parameters depends on the type. 

A VAR parameter passes a four-byte address of the actual parameter that can be used to 
reference the actual parameter via indirection. A value parameter passes the value of the 
expression that corresponds to the formal parameter. 

Boolean parameters occupy two bytes on the stack, but only the byte closer to the top of 
the stack contains valid data. This byte has the value of one for true and the value of 
zero for false. 

Character parameters use two bytes on the stack, but only the byte closest to the top of 
the stack contains valid data. This byte has the value of the ASCII code for the character 
passed in it. 
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Integer parameters occupy four bytes on the stack. They are stored as 32-bit 
two’s-complement numbers. Integer subrange types that fall into the range -128 to 127, 
inclusive, use type bytes on the stack, but only the byte closer to the top of the stack 
contains valid data. They are stored as 8-bit two’s-complement numbers. Integer 
subrange types that extend outside of the range -128 to 127, inclusive, but are within the 
range -32768 to 32767, inclusive, use two bytes on the stack. They are stored as 16-bit 
two’s-complement numbers. 

Real parameters occupy four bytes on the stack, with the sign bit being closest to the top 
of the stack. Real parameters occupy eight bytes on the stack, with the sign bit being 
closest to the top of the stack. Xreal parameters occupy ten bytes on the stack, with the 
sign bit being closest to the top of the stack. 

Set parameters require eight bytes on the stack, with the byte nearest the top of the stack 
containing bits 63-56 and the byte farthest from the top of the stack containing bits 7-0. 

Arrays and records occupy a number of bytes equal to their length, plus one if they are of 
an odd length. The filler byte is the byte farthest from the top of the stack. 

Strings should always be passed to assembly language routines as VAR parameters, due to 
the complexity of determining their actual size on the stack. 

Pointers require four bytes on the stack and they contain the address of the variable they 
reference. 


Registers 

The assembly language subroutine is responsible for preserving the value of registers A3, 
A5, and A6 during its execution. It is also responsible for removing from the stack all 
parameters passed to it by the Pascal program, and for storing a value in the return value 
location on the stack if the subroutine was declared as a function. 

The values of the A5 and A6 registers may be of use to the assembly language routine, 
since A5 points to the base of the global variable area and A6 points to the base of the 
local variable area of the procedure or function that was being executed when the 
assembly language routine was called. To reference a variable in either of these areas, a 
negative displacement from the register must be used. 

The assembly language subroutine is free to use the space between the top of the stack 
(pointed to by A7) and the top of the heap for local data storage. The address of the top 
of the heap is kept in the long word which is located in memory at a positive offset of four 
from the address in register A5. 

If A7 ever contains an address that is less than the address of the top of the heap, a 
stack/heap overflow condition has occurred. If a stack/heap overflow has occurred, then 
both the stack and the heap may contain invalid data. 
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Control may be returned to the Pascal program by means of either a return from 
subroutine instruction or a jump indirect through an address register which contains the 
return address. No matter which method is used, it is up to the assembly language 
subroutine to adjust the stack so as to remove the passed parameters. If the assembly 
language routine returned a function value, then A7 should point to that location on the 
stack where the space was reserved for the return value prior to the call. If the assembly 
language routine did not return a function value, A7 should point just below where the 
first parameter was pushed on the stack. 

The following is a picture of the stack for the SUMTHREE routine, seen earlier, just 
before the return to the Pascal program: 


TOP OF STACK ON ENTRY 


TOP OF STACK A7--> 

AT EXIT FROM FUNCTION 


FUNCTION VALUE 
SUMTHREE: 4 bytes; 
value =15 


low address 


high address 
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Commhead 

RECORD 




Actlist: Rmamedentity ; 
Actlock: Lock ; 

Mischead: Lock ; 

Fcnkill: Ptmamedentity ; 
Killer: Ptmamedentity ; 
Auclock: Lock ; 

Updlock: Lock ; 

Dcr: Ptrdcr ; 

RedAmbient: Intl6; 
GreenAmbient: Inti6; 

Blue Ambient: Inti 6; 
Packet_Received: BOOLEAN; 
NotUsed2: Int8; 

Rdyuph: Ptravupblk ; 

Rdyupt: Ptravupblk ; 

FSpointer: Integer; 
Dtroy_alpha: Rralphablk ; 
Dtroy_FI: Ptmamedentity ; 
Dtroy_IS: Ptrfcninputs ; 

Prilist: Fcn_pri_array ; 

Pritail: Fcn_pri_array ; 
Prilock: Fcn__lock_array ; 
Chfont: Ptmamedentity ; 
G_msglist: Rrmsglist; 
Hashlock: Lock ; 

Hashlength: Inti6 ; 

Hashtable: Ptrhash ; 


{ Active functions } 

{ Lock on Actlist } 

{ Lock on cheader fields } 

{ not otherwise locked } 

{ Dying functions } 

{ Their killer } 

{ Lock on alpha f/ -Usage } 

{ Lock on Pasuph/t } 

{ THE DCR } 

{ ambient light base color... } 

{ ... for shading ... } 

{ ... see SHADEINTF.DOC } 

{ for transfer indicator } 

{ Head: ACP fmt’d updates } 

{TaU: ... } 

{ Above here, known to ACP? } 

{ makes FS -error available V171 } 
{ Destroy* s name } 

{ its function inst. } 

{ its input set fen instance blocks } 

{ in priority order } 

{ head } 

{tail} 

{ Locks on each } 

{ Standard character font } 

{ Canned messages } 

{ Lock on the hash table & 1th } 

{ Length of the hash table } 

{ Dictionary of all names } 
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Parsedict: Ptxdictarr; 

ParseXcode: RrXcodearr; 

Headl: INTEGER; 

Head2: INTEGER; 

Functdict: Ptrfdictarr; 

Functable: Ptrfcnarray; 

PCperGCP: PtrPCpGCP ; 

FNany: Boolean ; 

FNptrlock: Lock ; 

Fnperuser: Ptxfnpuser ; 

FnperGCP: PtrfnpGCP ; 

Fcn_nact: Ptrintarray ; 

Fcn_ttim: Ptrintarray ; 

Fcn_mtim: Ptrintarray ; 

Last_ci_n: Inti6 ; 

Ini_sav_st: Ptrsavstate ; 

Std_chfont: Ptralphablk ; 

Password: Ptrqdata; 

Updsync: intl6 ; 

Notused4: Integer; Crash_dcr: Ptrdcr; 
Crash_lod: Ptmamedentity; 

TwoK^Location: PtrTwoK; 
setup_tables: ptrsetup; 

Plotinprog: Boolean; 

PlProgLock: Lock; 

Ibm_table: Ptribmtm; 

Ibm_device: Ptribmdevice; 
ASC_IBM_conv_table: Rrcnvtable; 
MvupO__pad: int8 ; 

Mvupl_pad: int8 ; 

Noupdates: Boolean ; 

Vupl_pad: int8 ; 

Vup2_pad: int8 ; 

Vup3_pad: int8 ; 

WhoAUPlot: ARRAY [1..4] OF CHAR; 

WhoPlLock: Lock; 

HCPiniComp: Boolean; 

PliniLock: Lock; 

MemOKlock: Lock; 

MemOKavailable: Arrmemok ; 
MemOKnumallocated: Arrmemok ; 
User_scopes: ARRAY [0..3] OF Scopearray; 
Schedstuff: Ptrschedarray ; 

Howtorun: pGCPshowtorun ; 
tap: Ptrtaprecord ; 


{ Normal command dictionary } 

{ expanded Pcodes for Normal } 

{ command syntax } 

{ really a PtrZHead: PS340 ScanLine- } 

{ ZBuffer head of edgepair linked-lists } 

{ Dictionary: function names } 

{ Table: function specs } 

{ PC report stats for each GCP } 

{ Should we bother to time fns } 

{ Gain right to change fnper* fields. } 

{ Per user fn report } 

{ Per GCP fn report } 

{ # of function activations } 

{ total running time of fens } 

{ maximum running time of fens } 

{ ID number for Cl; locked by Hashlock } 
{ initial save state } 

{ standard char font } 

{ password qstring } 

{ sync level (lock w/ Updlock) } 

{ for system wide crashes } 

{ for system crash messages } 

{ Loc to save MM for 2-k acp } 

{ Terminal setup information } 

{ Plot in progress } 

{ Plot in progress lock } 


{ so either here } 

{ halt updates iff noupdates } 

{ is false used in wrtback } 

{ pad Noupdates to .1 } 

{ to speed value updates } 

{ Which user has a plotter } 

{ allocated to self } 

{ Plotter allocation lock } 

{ No error during plot init } 

{ Plotter initialize lock } 

{ Multiple GCP requires } 

{ bytes left } 

{ bytes initially allocated } 

{ Log-phys scope map per user } 
{ for experiments } 

{ CPU allocation } 

{ For shoulder tap response } 
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Finuph: Ptxavupblk; 

Finupt: Ptravupblk; 

NotusedS: Inti6; UpKillFcn: Ptmamedentity; 
UpKillFlg: IntS; 

Type340: Char; 

Frametime: Inti6; 

Maxframetime: Inti6; 


GoOn: goontype ; 

VopFunction: Ptralphablk; 

Mcrash: tCrashinfo ; 

Scrash: tCrashinfo ; 

WrtBackFcn: Ptralphablk; 

Pasuphs: ARRAY [MemOKindex] OF Ptravupblk; 
Pasupts: ARRAY [MemOKindex] OF Ptravupblk; 


{ Finished update head } 

{ Finished update tail } 

{ Update killer function } 

{ Update killer flag } 

{ Type of 340 system } 

{ Seconds for frame—ACP timout } 
{ Max Seconds for sectioning } 

{ frame—ACP timout } 

{ Keepgoing in mass memory } 

{ viewing operation function } 

{ Info about crash in master } 

{ Info about crash in slave } 

{ Write back data function } 

{ Pascal update listheads } 

{ Pascal update listtails } 


Fmtfcns: ARRAY [MemOKindex] OF Ptmamedentity; { Update formatters } 
mem_thresh: INTEGER; { No big carves if they’ll go below this } 

no_mem_on: BOOLEAN; { Nomemsched is running } 

IBM3270 saved variables: Ptribm3270; 
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APPENDIX J 


Operation and Data Node Formats 


Operation Nodes 



An operation node is a data structure that modifies the state of the display processor. As shown 
in Figure J-1, an operation node consists of an integer that indicates this display structure is an 
operation node (=1), an integer that specifies the particular type of operation node, the 
descendant alpha, and a variable number of fields required by that particular type of operation 
node. For any operation node, bit 15 of the operation type is a conditional bit. If this bit is set, 
and if bit 15 (the blink bit) in the Condition Mask of the ACP State is zero, then the associated 
operation node is not performed. In all other cases, the operation node is performed. In all cases, 
the descendant of the operation node is traversed. Figures J-2 to J-28 detail each of the 
operation nodes. 


A box shown as 



indicates a long word ( 32-bits). 


NOTE 

Motorola uses the following Byte ordering: 


AO AO+1 



AO+2 AO+3 


This is different than the Byte ordering on a VAX: 


AO+l_^ 


2 

1 

4 

3 


AO+3 AO+2 
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Operation Node Formats 




Operation Node 

1 


Operation Type 


Descendent Alpha 

— 

Field 1 

Field 2 


• 



• 



' • 


Field n 


Figure J-1. General Operation Node Format 


NOTE 

A “C” in the left comer of the Operation Type block indicates the 
conditional bit (bit 15). 


Real # with 
Implied 
Exponent of 


Operation Node 


Operation Type 


Descendent Alpha 


X Center 


Y Center 


Z Center 


X Size 


Y Size 


Z Size 


Viewcon 


i.. 


Viewport 

Center 


Viewport 
Size 


Figure J-2. Viewport 



- Descendent Alpha - 


Operation Node 


Operation Type 


Exponent 


M (1.1) 


M (1,2) 


M (2,1) 


M (2,2) 


= Matcon2 


Figure J--3. Character Rotate, Character Scale, Character Size, Matrix_2x2 



y-2 
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= MatconS 


0 = No Translation 
Follows 


Figure J-4. Rotate, Scale, Matrix_3x3 




= Matload4 

(Row 4) 
(Row 1-3) 


Figure J-5. Window, Eye Back, Field_of_View, Matrix_4x4 


Operation Node 


Operation Type 


Descendent Alpha 


Exponent 


Tx 


Ty 


Tz 


= Translate 


Figure J-6. Translate 

ri 
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Operation Node 

1 

1 

Operation Type 

6 

- Descendent Alpha - 


Figure J-7. Increment Level-of-Detail 



Operation Node 

1 

C 

Operation Type 

7 

— 

Descendent Alpha 

— 


= DecLOD 


Figure J-8. Decrement Level-of-Detail 


Operation Node 


Operation Type 


Descendent Alpha 


Wordindex 


Offmask 


Onmask 


Change Bits 



Figure J-9. Set Level-of-Detail, Set Conditional Bit, 

Set Displays, Set Character Orientation, 

Set Contrast, Set CSM, Set Depth_Clipping, 
Set Plotter, Set Rate External, 

Set Blinking(PS 350 only). 

Set Line_Texture(PS 350 only) 


NOTES 


Wordindex = 0 

- LOD value 

1 

- Conditional bits 

2 

- Line Generator Mask 

3 

- Enable/PLS Mask 

4 

- Line Texture value 


KJ 
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The changebits operate node is created by several different PS 300 user 
commands. Its format is shown above. These PS 300 commands 
determine the wordindex and also the offmask and onmask. When 
encountering this node in the structure, the ACP processor locates the 
correct mask according to the wordindex value. It then modifies the bits 
in this mask by turning off the bits indicated in the Offmask and then 
turning on the bits indicated in the Onmask. 


Command 

Wordindex 

Bits used 

Offmask 

Onmask 

Set LOD 

0 

0-15 

16#FFFF 

LOD value 

Set conditional_bit n on 

1 

n 

XX 

XX 

Set conditional_bit n off 1 

where XX is the 16 bit word with bit n set 

n 

XX 

0 

Set csm on 

2 

6 

16#0040 

0 

Set csm off 

2 

6 

1680040 

168040 

Set displays all on 

2 

12 

16#1000 

0 

Set displays all off 

2 

12 

16#1000 

16#1000 

Set plotter on 

3 

11 

.16#0800 

16#0800 

Set plotter off 

3 

11 

16#0800 

0 

Set picking on 

3 

15 

16#8000 

16#8000 

Set picking off 

3 

15 

16#8000 

0 

Set depth_clip on 

3 

2 

16#0004 

0 

Set depth_clip off 

3 

2 

16#0004 

16#0004 

Set char world_oriented 

3 

12,13 

16#3000 

0 

Set char screen_oriented 

3 

12,13 

16#3000 

16#2000 

Set char screen/or/fixed 

3 

12,13 

16#3000 

16#1000 

Set Line_texture 

4 

2-8 

16#3FC 

Texture 

Set Line_texture contin 

4 

2-8,9 

16#3FC 

16#0020 

OR Texture 



o 
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<j 


= Bit Test Conditional 
Mask 


Figure J-10. IF Conditional_Bit, IF Phase (Bit 15) 

NOTES 

C TYPE = 0 Bit off 
1 Bit on 


= Value Test 
Level of Detail 


C TYPE = 2-Les 

3- Eq 

4- Leq 

5- Gtr 

6- Neq 

7- Geq 
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rs 



= Mats Trans 


1 = Translation 
Follows 


Figure J-12. Look At/From, Matrix_4x3 



Real # with 
Implied 

Exponent of 0 


Operation Node 


Operation Type 


11 


Descendant Alpha 


Y Max 


Y Min 


X Max 


X Min 


= Trypick 


Figure J-13. Set Picking Location 



Operation Node 

1 


Operation Type 

12 

— 

Descendant Alpha 

— 

- Previous Pick Node - 

- Alpha Pickname - 


= Pickname 


Figure J-14. Set Picking Identifier 




Operation Node 

1 


Operation Type 

13 

— Descendant Alpha - 

E 

Char Font Alpha 

— 


= Set Charfont 


Figure J-15. Character Font 
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Operation Node 1 


Operation Type 14 

-— Descendent Alpha - 

Hue 

Saturation 


= Set Color 



Figure J-16. Set Color, Set Color Blending 
NOTES 

Saturation = 4 bits (bits 6..3) All bits set is maximum saturation 
Hue = 7 bits (bits 14..8) Clear Hue = 0, all bits set is max hue 

Blending = 1 bit (bit 15) Set = blending, clear = no blending 


= Set Blink Mode 




Ct = Value counting down to zero; 
b = Blink bit; set initially to 1 
Blink on for M 
Blink off for N 


Operation Node 


Operation Type 


15 


Descendent Alpha - 


Ct 


^ ////////////////////////////// 


M 


N 


Figure J-17. Set Rate 
NOTES 


Real # with 
Implied 
Exponent of 



Operation Node 

1 


Operation Type 

16 


Descendent Alpha 

— 

Intensity flag 

Z Center 

Z Size 



= Set Intensity 


If zero, ignore 
this node. 


Figure J-18. Set Intensity 
NOTES 


Center is minimum intensity. 

Size is the difference between minimum and maximum. 
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Operation Node 

1 


Operation Type 

18 

— 

Descendent Alpha 

— 

— 

Destination Alpha 

— 

Figure J-19. Xform Matrix 


Operation Node 

1 


Operation Type 

19 


Descendent Alpha 

— 

— 

Destination Alpha 

— 

Figure J-20. Xform Vector 


Operation Node 

1 

C 

Operation Type 

21 

- Descendent Alpha - 

Progress flag 

Data node count 

Vector coimt 

max. data node count 

— 

Progress flag 

— 

— 

Progress flag 

— 


= Xforml 


= Xfonn2 


= Wrtdata 


Figure J-21. Writeback 



_ Perform Viewing 
Operation 


Exponent 141 - 144 
Exponent Ill - 134 


Identity matrix 


144 jj 


Figure J-22. Solid_Rendering, Surface_Rendering 
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_ Define Sectioning 
Plane 


Exponent 141 - 144 
Exponent Ill - 134 


111 ^ 

112 


^ Identity matrix 


144 ]) 


Figure J-23. Sectioning Plane 


C 


Operation Node 
Operation Type 
Descendent Alpha 
Node on/off 
Control word 
Delta Position 
Sample Counter 
Use New X,Y 
Not used 
New X 
New Y 


1 

26 


= Lightpen 


Position delta limit 
Sample count to output 


User specified cross X 
center. 

User specified cross Y 
center. 



Figure J-24. Light Pen (PS 350 only) 
NOTES 


Node on/off: 

Bit 6 — Set if you have not triggered this operation node. (USER.NODE.OFF) 

5— Set if the GCP wants the AGP to display only a tracking cross. 
(GCP.NODE.OFF) 

Control word: 

Bit 9 — Set if screen blast enabled. (BLAST.ON) 

8 — Set if a tracking cross enabled. (CROSS.ON) 

7 — (Set if the debug mode enabled — company confidential) (LP.DEBUG) 
Use new XY: 

Bit 10 — Set if you specified (X,Y) coordinate is used to position a tracking cross. 
(NEWXY.ON) 

New X and New Y: 

They must be values in the range from X’4000’ to X’COOO'. Where X’4000' is 
assumed to be 1 and X’COOO’ -1. 
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Data Nodes 


A data node is the display structure primitive that causes data to be drawn by the ACP. A data 
node consists of an integer that indicates this display structure is a data node (=2), an 8~bit field 
that specifies the mode of vectors in the data node, an 8-bit integer that specifies the particular 
type of data node, a 32-bit integer which points to the next data node of identical data type, an 
integer (n) that specifies the number of vectors, polygons or characters in the data node, a 16-bit 
integer that specifies the pick index, and either vector data (including polygons) or character 
data. Vector data consists of the two- or three-dimensional vectors (preceded by polygon 
attribute information if polygons). Character data consists of an initial translation, spacing 
information, and the character string. The general format of a data node is illustrated in Figure 
J-29. 



Figure J-29. General Data Node Format 

Mode, data type, pick index, and vector/character data are detailed further below. 
• Do_Dots Field 

The Do Dots field of a data node consists of: 


15.9 

8 

7 ... . 0 

Unused 

D 

T 

Data Type 


Do_Dots Field-’ 

= 0 for no endpoint intensification 
= 1 for endpoint intensification 


The Do_Dots field of a data node is a single bit that specifies how the vectors are to be 
drawn. When dot mode = 0, vectors are drawn normally. When dot mode = 1, each 
endpoint of the vector list is drawn as an intensified dot. 


Figures J-30 through J-41 show formats for PS 300 and PS 350 data nodes. 
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PS 300 Data Node Formats 




Data Node 


Do Dots 


Data Type 0 


Pointer to Next Data Node 


Pick Index 


XI 

Y1 

Z1 


Exponent 1 


X2 

Y2 

Z2 


Exponent 2 


Xn 

Yn 

Zn 


Exponent n 


Intensity 1 


Intensity 2 


Intensity n d 


= Vec3f0 


Figure J-30. Vector^List N=n X1,Y1,Z1 X2,Y2,Z2 ... Xn,Yn,Zn 
Vector-Normalized (Full Vector) - 3D (yec3f0) 


Data Node 

2 

Do_Dots 

Data Type 

1 

- Pointer to Next Data Node - 

n 

Pick Index 

XI 


Yl 


Exponent 1 

Intensity 1 


X2 


Y2 


Exponent 2 

Intensity 2 





• 


Xn 


Yn 


Exponent n 

Intensity n 



= Vec2f0 


Figure J-31. VectorJList N=n XI,Yl,— X2,Y2,— ... Xn,Yn,— 
Vector-Normalized (Full Vector) - 2D (Vec2f0) 
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Figure J-32. 


Figure J 



Data Node 2 

Do_Dots 

Data Type 2 

— Pointer to Next Data Node - 

n 

Pick Index 

Exponent 1 

Intensity 1 

XI 

Y1 

Z1 

/ 

/ 

d 

X2 

Y2 

Z2 

/ 

/ 

d 

• 

• 

• 

Xn 

Yn 

Zn 

/ 

/ 

d 


= Vec3bO 


Vector_List Block N=n X1,Y1,Z1 X2,Y2,Z2 ...Xn,Yn,Zn 
Block-Normalized - 2D (Vec3b0) 


Data Node 

2 

Do_Dots 

Data Type 

3 

— Pointer to Next Data Node - 

n 

Pick Index 

Exponent 1 

Intensity 1 

XI 

/ 

Y1 

d 

X2 

/ 

Y2 

d 


• 



• 



• 


Xn 

/ 

Yn 

d 


= Vec2b0 


33. Vector^List Block N=n XI,Y1 X2,Y2 ... Xn,Yn 
Block-Normalized - 2D (Vec2b0) 
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Data Node 

2 

Do_Dots 

Data Type 

4 

- Pointer to Next Data Node 

— 

Number of Characters 

Pick Index 

Tx 

Ty 

Tz 

Exponent 

//////////////// 

Delta X 

Delta y 

Char 0 

Char 1 

Char 2 

Char 3 

• 


• 


• 


• 


• 


• 



= Dstring 


Figure J-34. Characters, Labels 
NOfES 

Pick Index is always 0 for Characters, 0 for first label, 1 for next 
label, etc. 

A label block with only one label is indistinguishable from a character 
node. 


Data Node 


Do Dots 


Data Type 5 


Pointer to Next Data Node 


Pick Index 


Light Source X 
Light Source Y 
Light Source Z 


Exponent 


Intensity 


Light Source Red 


Light Source Green 


Light Source Blue 


Ambient 


Next Light Source - 


= ShadeLight 



Figure J-35. Illumination 
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Data Node 

2 

Do_Dots 

Data Type 

8 

- Pointer to Next Data Node - 

n 

Pick Index 


o/c 

Fill Type 

Hue 

Sat 


• 

n 

XI 

Y1 

Z1 

Exponent 1 

Intensity 1 






• 






» 






» 


Xn 

Yn 

Zn 

Exponent n 

Intensity n 






• 






• 






• 



= Vecpoly 

Number of polygons 

Fill type: solid,hatched, 
no fill, etc. 


Closure for each polygon 
is implicit: the vector 
from vertex n to vertex 1 
is generated by the 
microcode. 




Figure J-36. Polygon 



NOTES 


Abbreviations: 

u - Color use: 0 = ACP state, 1 = specified. 

o/c - Original/capping surface: 0 = original, 1 = capping. 

c - Continue flag: 0 = begin new polygon, 1 = continue polygon from previous 
node. 

t - Polygon type: 0 = first polygon of a planar surface, 1 = 2nd to mth polygon of 
planar surface. 

d - Edge visibility: 0 = invisible edge, 1 = visible edge. First vertex defines visibility 
of closing edge, second vertex of first edge, etc. 
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PS 350 Data Node Formats 


Note: Fields marked by asterisks are not used nor accessed by normal ASCII and GSR 
commands. The top bit in the second word of each of these formats (labeled “A”) is a flag 
which, if clear, tells the display structure walker to process these fields. This bit is set by default, 
and there exists no command to clear it. Advanced user-written functions and programs using 
the physical read/write facility may however, use these fields and clear that flag. 


rs 


Data Node 


Do Dots 


Data Type 6 


Pointer to Next Data 


Ntimber of Characters 


Pick Index 


Line Texture 


Traverse Cnt 


Color 


Tx 


Ty 


Tz 


Translation Exponent 


//////////////// 


Exponent 


M (1,1) 


M (1,2) 


M (2,1) 


M (2,2) 


Delta X 


Delta y 


Char 0 


Char 2 


Char 1 


Char 3 


= DstringD 


> Character Translation 


2x2 Character Matrix 


Spacing between 
Characters 


Figure J-37. Characters, Labels Character string (DstringD) 


NOTES 




Pick Index is always 0 for Characters, 0 for first label, 1 for next 
label, etc. 

A label block with only one label is indistinguishable from a character 
node. 
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= Vec3bs2 


Figure J-38. Vector_List Block N=n Xl.Yl.Zl X2,Y2,Z2 ... Xn,Yn,Zn 


= Vec2bs2 


Figure J-39. Vector_List Block N=n XI,Y1 X2,Y2 ... Xn,Yn 
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Data Node 2 

0 

Do_Dots 

Data Type 14 

- Pointer to Next Data Node - 

n 

Pick Index 

Line Texture 

Traverse Cnt 

Color 

Exponent 

Intensity 

0 

XI (H) 

XI (L) 

0 

Y1 (H) 

Y1 (L) 

0 

Z1 (H) 

Z1 (L) 

— 

/ 

d 

0 

XI (H) 

XI (L) 

0 

Y2 (H) 

Y2 (L) 

0 

Z2 (H) 

Z2 (L) 

/ 

d 

• 

# 

• 

n 

0 

Xn (H) 

Xn (L) 

0 

Yn(H) 

Yn (L) 

0 

Zn (H) 

Zn (L) 

/ 

d 


= Vec2bd0 


Figure J-40. Vector^List N=n X1,Y1,Z1 X2,Y2,Z2 ... Xn,Yn,Zn 
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Error Types/Error Numbers 


There are three crash error types in the PS 300. Each type has a set of error numbers associated 
with the type. The three types are: 


1. System Errors 

2. Traps 

3. Exceptions 




The following is the list of errors for each type. 

Type 1 - System Errors 

1 Track number out of range 

2 Disk drive not ready 

3 Disk remains busy after a seek 

4 Block number out of range 

6 Lost data during read 

7 Record not found during read 

8 Data CRC error during read 

9 ID CRC error during read 
B Lost data during write 

C Record not found during write 
D Data CRC error during write 
E ID CRC error during write 
F Write fault 

10 Disk is write protected 

11 Lost data during format 

12 Write fault during format 

14 Disk drive number out of range 

15 Seek error 

16 Drive not ready during read 

17 Drive not ready during write 

18 Disk not at track 0 after restore command 

19 Disk busy after restore command 
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lA Track number out of range during format 
IB Drive not ready during format 
1C Disk write protected during format 
ID Time out during read 

IE Time out during write 

IF Time out during format 

64 Wait maybe called with nil argument 

65 Wait maybe called with a non-function 

66 Wait maybe, already a function waiting 

67 Wait maybe, parameter function waiting elsewhere 

68 Q ship to an unrecognized Namedentity 

69 Msgcopy, Message type shouldn’t be copied 

6A Msgcopy, Msg type Has structure, unknown to Msgcopy 

6B Send, ’Me* = nil 

6C Send, ’Me’ not a function instance 

6D Send, No such output port for this function 

6E Rem_conn/Add_conn, A1 = nil 

6F Add_conn, A2 = nil 

70 Findqueue, Named item = nil 

71 Findqueue, illegal queue number (queue no. < 0 or queue no. > no. of inputs 
for function) 

72 Allinpwait, Nmin > Nmax 

73 Allinpwait, Nmin < 1 

74 Tmessage, Waiting and n = 0 

75 Cmessage, Waiting and n = 0 

76 Lookmessage, Waiting and n = 0 

77 Allinputs, Nmin > Nmax 

78 Allinputs, Nmin < 1 

79 Fcnnotwait, Me = nil 

7A Findqueue, found a nil queue! 

7B Waitnextinput, n = 0 

7C Any outputs, Me = nil 

7D Anyoutputs, illegal outset number 

7E Anyoutputs, no outset where there should be 

7F Fdispatch, function failed to re-queue after running 

80 Text_text, B1 < 0 

81 Char_text, b < 0 

85 Error during disk read 
8D Initial structure not correct 
8E AnnoimceUpdate List tail = nil;head < > nil 
8F FormatUpdate Somebody’s sleeping in my bed 

90 FormatUpdate Ready Head not nil but Tail is 

91 Bad code file — illegal Op 

92 Byteindex Invalid Acpdata type 

93 FormatUpdate, PASCAL Head not nil but Tail is 

94 Vec_size, Invalid Acpdata type 

95 KillUpdate, Updfetch was < 0 
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96 KillUpdate, Some one was sleeping in my bed 

97 Vec_bias, Invalid Acpdata type 
99 CntCapacity, Invalid Acpdata type 
9C Unknown brand of Namedentity 

9D Hasstructure knows something I don’t 
9E Amnhead not a Qalphapair 
A1 AppendVector, Invalid Acpdata type 
A3 Nomemsched, Bad .Status for a fen 
A9 Bad update list on AGP time-out 
AA AGP Timeout during initialization 
AB Grashprepare, Name GRASHS has not been defined 
AG DecUpdsync, G_header " .Updsync < 0 

AD FormatUpdate, Someone waiting in G_header " .Updswait already 
AF Someone else waiting in G_header " .Killer already 
BO Non-nil Qwait of a dying function 
B3 Microcode won’t fit into AGP 
B4 Implementation limit on delta waits (2**31) 

B8 detected internal inconsistency 
B9 detected error (passed a bad parameter) 

BA diskette’s parsecode table inconsistent with parser 

BD Bad boundary on binary data xfer 

BF default Devsts contains errors 

GO Inwait, f is already waiting or not a function 

G1 Outwait, f is already waiting or not a function 

G2 EGO Level of GGP does not support 56K Baud Line 

G3 Port 1 Gonfiguration is invalid for 56K Baud Line Support 

G9 User generic function stack overflow 

GA Ug_run_cnt has become negative 

GB User generic function has bad alpha (on private queue) 

GG Bad format of MSGLIST .DAT detected 
GD MSGLIST (or code using it) has probably been corrupted 
GF Apparent datastructure incompatibility 
DO Bad MemOKindex detected 
D1 routine passed bad parm (e.g., a nil ptr) 

D2 Lines to^ IBM system not active 

D3 Floppy disk file INITGPIO.DAT; not found or unable to read 

D4 Floppy disk file GPIOGODE.DAT; not found or unable to read 

D5 Floppy disk file IBMFONT.DAT; not foimd or unable to read 

D6 Floppy disk file IBMKEYBD.DAT; not found or unable to read 

D7 Floppy disk file IBMASGII.DAT; not found or unable to read 

D8 IBM GPIO timeout 

D9 No. of minimum inputs is negative 

DA No. of maximum inputs < No. of minimum inputs 

DB No. of maximum inputs > # inputs for function 

DG Sendlist detected a bad list 

DE Sendmess: message to be sent is NIL 

DF Galler did not have a lock set already 
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EO Curfcn in improper state to call Getinputs 

El Cleanin, Curfcn in improper state to call Cleaninp (e.g., have you first called 
Getinputs?) 

E2 Somebody remembered a forgotten non-fcninstance 

E5 Alpha not already locked by caller 

E6 Confusion in discarding bad message 

E7 Lock not already set by caller 

E8 Probable multiple master GCPs 

E9 RemOne, Curfcn does not have that many inputs 

EA RemOne, Message to be deleted and message pointed to by Curinputs is not the 
same 

EB Lock not already set in Gatheraupdate call 
ED Get21ocks detected lock already set 
EE Error in semantic routine for polygon vertex 
EF Destination Alpha was not already locked 
FO Parent not already locked in add/remove from set 
FI Child not already locked in add to set 
F3 Alpha not already locked in Gpseudoaupdate 
F6 Confusion about locks or decausages 
F7 Unknown tap reason 

F8 Unanticipated state at which to see shoulder tap 

F9 Illegal number of inputs 

FC No existing DCB found for this user 

FD Timeout, Message on input 1 disappeared before fen could get it 
FE Error while initializing disk drive 
FF Error while reading disk header 

100 Error while reading disk directory 

101 THULE.DAT not foimd on disk 

102 Error while reading THULE.DAT 

103 Curfcn was not active at entry 

104 Viewport not in structure 

105 Real_simple, number of digits requested out of range (n < 1 or n > 9) 

106 Getnextone, illegal queue specified 

107 Getnextone, msg on head of queue and specified by Curinput do not agree 

108 Getnextone, no message on queue, but Curinput < > NIL 

109 ContBlock, nil block 

10A Timeout when waiting for all on-line GCPs 
lOB Rehash only works first time, only time now. 

IOC No processor has right to issue this tap 
lOD GetVector, Not an Aepdata block 
lOE GetVector, Not a vector Aepdata block 
lOF Invalid qpacket received 

110 Tolerance on FCnearzero is absurd 

111 set construct of father has no dummy control block 

112 function code has to be of type Cl to have elements included and removed 

113 ShadeEnviron node encountered in non PS 340 
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Error TypeslError Numbers 


Type 2 - Traps 

0 No mass memory on line, or too little to come up 

1 More OKINTs than NOINTs or > 128 NOINTs 

2 Free storage block size bad (on request or in free list) 

3 Attempt to Activate a non-function (or nil) or bad software detected during startup 
(most commonly, incompatible datastru.sa detected but perhaps invalid startup 
routine sequencing (if someone has been mucking around with it)) 

4 NEW call failed to find memory, within NOMEMSCHED 

5 Attempt to queue where a function is already waiting 

6 Systemerror(n) 

7 Badfcode(Fcn) 

8 Mass Memory Error Interrupt 

9 Utility Routine not included in this linked system 
A Probable multiple DISPOSE of the same block 

B Block exponent not big enough 

C Attempt to divide with a divisor which is too small in FixLongDivide (twice the 
dividend must be less than the divisor) 

D (Used by Motorola PASCAL) 

Type 3 - Exceptions 

0 Reset: Initial SSP 

1 Reset: Initial PC 

2 Bus Error (i.e. attempt to address nonexistent location in memory) 

3 Address Error (i.e. attempt to access memory incorrectly, for example an 
instruction not starting on a word boimdary). 

4 Illegal instruction 

5 Zero Divide 

6 CHK Instruction 

7 TRAPV Instruction 

8 Privilege violation 

9 Trace 

10 Line 1010 Emulator 

11 Line 1111 Emulator 
24 Spurious interrupt 
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U5ERUPDATES 


PS 300 USER GUIDE FOR THE UPDATES FUNCTION 


NOTICE 

The Updates Function, F:USERUPD, is preliminary and may 
contain bugs. The functionality of the FrUSERUPD may 
change in response to feedback from the users of this 
function. E&S has provided FiUSERUPD so that those users 
who need the ability to perform fast updates via an RS-232 
line may use the function to determine if it meets their 
needs. E&S makes no commitment to maintain the 
functionality of FiUSERUPD in its present form. 








PREFACE 



The Updates Function, F:USERUPD, was created to allow data structures to be updated 
quickly by transferring data from the host to the PS 300 very rapidly. FrUSERUPD is 
an enhancement included with Graphics Firmware Version A1 that can be used with all 
PS 300 interfaces and all members of the PS 300 family of computers except the PS 340. 

This document is intended for PS 300 Graphics System users who are very familiar with 
the PS 300 Gommand Language and would like to use the PS 300 for robotics, 
animation, or sir^tulation. These applications require that the host computer update 
viewing transformations and characters rapidly, a capability now provided by 
FiUSERUPD. 

This document describes the FiUSERUPD function and details its use but does not 
describe how data are handled once they are sent to the function. 
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1. INTRODUCTION 


Applications for robotics, animation, and simulation require rapidly updated viewing 
transformations. USERUPDATES (FrUSERUP) is a function that allows data structures 
to be rapidly updated on the host and transferred to the PS 300 faster than ever before 
possible. 


Transferring data using the F:USERUPD consists of the following steps: 

• Instancing the F:USERUPD function. When the function is instanced, it creates 256 
names ( Function Instance name 001 through Function Instance name 256). 

• Creating a display structure using the names created by F:USERUPD, to update the 
transformation nodes in that display structure. 

• Setting up F:USERUPD by sending the bytes that describe SET count, update types, 
and indices. 

• Updating the data structure by sending the data SET. 


D 
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2. TRANSFORMATION UPDATES SUPPORTED BY F:UPUSERUPD 



The updates supported by FiUSERUPD are listed below. Each update is identified by a 
unique number. 


Update 

Update Type 

Number of Bytes 
Transmitted 

Description 

1 

Rot in X 

2 

Angle 

2 

Rot in Y 

2 

Angle 

3 

Rot in Z 

2 

Angle 

4 

Rot in XYZ 

6 

Angles for XYZ axis 
(rotated in order) 

5 

Tran in X 

3 

X coordinate 

6 

Tran in Y 

3 

Y coordinate 

7 

Tran in Z 

3 

Z Coordinate 

8 

Tran in XYZ 

9 

XYZ coordinates 

9 

String 

1 

string length 

string length 
string 

10 

Window 

18 

Xmin, Xmax, Ymin, Ymax, 
Front, Back 

11 

Look From 

27 

From XYZ, At XYZ, Up XYZ 

12 

Field of View 

8 

Angle, Front, Back 

13 

Scale 

9 

XYZ Scale factors 



The angle for rotations and the coordinates for translations have to be sent in a 
particular format to this function. To minimize the number of bytes transmitted on the 
communication line between the host and the PS 300, numeric values are represented in 
angle values or a floating point format. 
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Angle Values 


The angles for the rotations are represented as 65,536*'^® of 360 degrees. All 
angles must be positive. The angles are sent as two bytes with the high order 
Byte being sent first. Representation for some common values follows: 


ANGLE 

(Degrees) 

BYTES 

(High) 

(HEX) 

(Low) 

0 

00 

00 

45 

20 

00 

90 

40 

00 

180 

80 

00 

270 

CO 

00 

360^65,535 

EE 

EE 


65,536 



Floating Point Format 


Floating-point numbers are represented by three bytes each. The first byte 
represents a sign bit and a base two excess 64 exponent. The mantissa sign bit is 
the most significant bit of this first byte. The next 2-byte field is a normalized 
17-bit fraction with the redundant most significant fraction bit not represented. 
The high-order byte of the fraction is sent first. A detailed example is given at 
the end of this document. 

DECIMAL NO . SIGN/EXPONENT MANTISSA (HEX) 


0 

.5 

1 

-3 


00 

40 

41 
C2 
43 


00 00 
00 00 
00 00 
80 00 
40 00 



5 
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Each update will generate an output directed to predetermined data structures 
which are generated when the function is instanced. 


NOTE 

The examples in this document assume that you have some 
knowledge of how floating point numbers are represented 
in computers. 
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3. UPDATE SET 


Updates which are repeatedly carried out are termed as a SET. The number of updates 
in a SET is the SET COUNT. After the system is initialized, each SET of updates is 
sent from the host or the keyboard to the PS 300 in the following format. 




■ HEADER 

Char(6) 

Data 

Byte 

Data 

Byte 

Data 

Byte 

Data 

Byte 

Data 

Byte 

Data 

Byte 


Each SET contains a SET HEADER ( CHAR(6) ) byte to indicate the beginning of data 
for that SET. This is then followed by data bytes, the number of bytes depending on the 
types of updates in that SET. For example, if the set contained two updates, a ROT in 
XYZ and a TRAN in X then the number of data bytes for that SET would be 9 (6 bytes 
for the three angles and 3 bytes for the X coordinate). 

The updates will NOT be performed until all the data bytes are received for the 
particular SET of updates. It is your responsibility to ensure that the data bytes are 
sent in the correct format. Failing to adhere to this will produce unpredictable results 
or a SYSTEM CRASH as there is no system check for this condition. 

The names are generated at the time the function is instanced. For example: 

MTUP:=F:USERUPD; 



will create 256 names MTUPOOl, MTUP002,.MTUP256. 
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4. INITIALIZATION SET 


Once the function is instanced, data for the types of updates and the index to the 
associated names have to be sent to the function by The host or from the keyboard. 
This information is sent to the function only once. It determines the number of updates 
in the SET (namely SET COUNT), and (for each update) the number corresponding to the 
type of update, and the index corresponding to the name this update is to be directed to. 


o 


NOTE 

The only way this information can be changed is by 
re-initializing the function which is accomplished by 
re-instancing it. 


The index is the number corresponding to the name. If the index is 5, then in the 
previous example, the update will be directed to MTUP005. Once this information is 
sent to the function by the host or from the keyboard, data can be sent to this function 
continuously in the format described earlier. 

The format in which initialization data have to be sent is as follows: 


SET HEADER 
SET COUNT 
Update Type 
Index 


Char(6) 

Number of Updates in Set 
Char(l) thru Char(13) 
Index into the Names 


Update Type Char(l) thru Char(13) 


Index 


Index into Names 
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The name of the function can be any vaild PS 300 name. Thus, to update 
transformation nodes within a data structure, use the following format. 


World.myupdate := F;USERUPD; 

World := BEGIN STRUCTURE 

Myupdate 001 := WINDOW ... ; 
Myupdate 002 := ROTATE IN X 0; 
ENDSTRUCTURE; 


CAUTION 

It is your responsibility to make sure that the numbers 
corresponding to the Update type and the indices are 
within limits. No checks are made by the function to 
ensure that the values are correct. 

Failure to do so will result in a SYSTEM CRASH without a 
warning. There are NO DEFAULT VALUES for the 
window, look from, scale, and field of view commands. 
ALL parameters must be sent each time. For example; for 
the field of view command, the angle as well as the front 
and back boundaries have to be sent to the function every 
time when performing a SET of Updates which includes this 
command. 



This function is very easy to use once you are familiar with the PS 300 Command 
Language. An example demonstrating the use of this function from the keyboard 
follows. The same outcome can be accomplished by sending the data from the host. 

PP:=F:USERUPD; 

PP001:= ROT 0 THEN PP002; 

PP002:= TRAN BY 0,0 THEN V; 

V:=VEC 0,0 .5,.5 -.5,.5 0,0; 

DISP PPOOl; 


{Set up F:USERUPPD} 



o 
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SEND CHAR(6)&CHAR(2)&CHAR(2)&CHAR(l)(5cCHAR(5)&CHAR(2) TO <1>PP; 

{ Note the format of the data } 

{ Set header, set count, uptype,index, uptype,index } 

{ This indicates a rotate in Y directed to 1 and trans in X } 

{ Directed to 2 } 

{ Update data} 

SEND CHAR(6)&CHAR(64)&CHAR(0)(5cCHAR(6A)(5cCHAR(0)(5cCHAR(0) TO < 1 >PP; 
{ This will rotate the object 90 degrees in Y and translate .5 in X } 
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5. FLOATING POINT EXAMPLE 


EXPONENT BYTE 


O 


(Excess - 6A) 


I Mantissa Sign Bit 
V_ 

I s I I I I I 1 r~ 

BIT 7 6 5 4 3 2 1 0 


17 BIT MANTISSA 


BIT 


Hidden Bit 

I -high byte-1-LOW BYTE- 

1 1 I I 'I 1 I I I I I •] n.T~i j ■_[ j e: 

16 15 14 13 12 II lO 9 8 7 6 5 4 3 2 I 0 
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To elaborate on this example, observe the following representation of the 
floating number 9.0 


Real number = (2**Exponent x Mantissa) / (2^^17) 

[(2*^17) represents the number of bits in the fractional part.] 


Exponent 


= 68 (68 - 64 = 4) 


9.0 = (2*^4 X Mantissa) / (2^^17) 


Mantissa 


9.0 X 2*^13 
(2*^3 -h 1) X (2^^13) 
2^^16 + 2^^13 
Hidden Bit + Bit 1 3 




HIGH BYTE = 32 (Decimal) = 20 (Hex) 


LOW BYTE 

= 0 

(Decimal) = 0 (Hex) 


Number 

EXP 

HIGH BYTE 

LOW BYTE 

9.0 


20 

00 (HEX) 

9.0 

68 

32 

00 (DECIMAL) 


The value of the exponent is the unsigned integer represented by the exponent 
bits minus the excess of 64. Thus, the exponent 1 is represented as the number 
65 (65-64=1) and the exponent -1 is represented by the number 63 (63-64=1). 

By convention, the real number 0 is represented by a value of 0 in the exponent. 

The fractional part of the real number is normalized such that 1/2 >_ [fractional 
part] < 1. 
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6. PROGRAM EXAMPLES 


The following programs are contained on the PS 300 magnetic tape labeled PSDIST 
distributed with the A1 version of the Graphics Firmware. The file UPDATE.DAT also 
contained on the PS 300 magnetc tape should be loaded on the PS 300 before any of the 
program examples are run. 


PUPDATE.PAS - PASCAL EXAMPLE 



PUPDATE.PAS is a program example of how to use the F:USERUPD function to 
perform fast updates over an RS-232 communications line. This program is 
contained on the PS 300 magnetic tape labeled PSDIST and uses the E&S supplied 
GSR routines to send the data to an instance of USERUPD. 

The program assumes that the file UPDATE.DAT has been loaded into the 
PS 300. UPDATE.DAT contains the data structures to be updated, and also 
instances F:USERUPD, initializes it, and connects it to output <11> of 
CIROUTEO. The program updates five rotation nodes, one translation node, and 
a character string. 

The structure being updated is a simple robot arm. Although the program does 
not demonstrate all updates that are possible using F:USERUPD, it does 
demonstrate a mechanism for building all of the data types that FiUSERUPD 
acknowledges. Refer to Volume 5 for instructions on compiling and linking this 
program. 

"GSRLIB" is a VAX logical name for the directory containing the GSR files. The 
program assumes that the error handling procedure is named "ERRHAN" and that 
it resides in the same directory as the GSR files. 
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Program HostUp ( input, output ); 

CONST 

{GSR const declarations} 

“/.INCLUDE 'GSRLIB:PROCONST.PAS/noliSt■ 

TYPE 

(GSR type declarations} 

yjNCLUDE 'GSRLIB:PROTYPES.PAS/nolist' 


String = Varying [80] of Char; 

Int8 = [bytelO..255; 

Intl6 = -32768..32767; 

{ a variant record makes it easy to get the pieces of a vax real } 
Vax_real = PACKED RECORD 
CASE BOOLEAN OF 

TRUE: ( fr2: 0..127; 
junk: Boolean; { can't use this bit } 
exponent: 0..255; { place wants sign in exponent } 
frO.frl: Int8 ); 

FALSE: ( r: Real ); 

END; {record} 


current_angle : VARYING [2] OF CHAR; { USERUPD angles are 2 bytes} 
current_real : VARYING [3] OF CHAR; { USERUPD reals are 3 bytes } 
current_str : P_VaryingType; { USERUPD strings are } 

{ up to 255 bytes } 

Cnt : Integer; 

Upl.IncUpl : Real; 

Up2,IncUp2 : Real; 

Up3,IncUp3 : Real; 

Up4,IncUp4 : Real; 

Up5,IncUp5 : Real; 

Up6,IncUp6 : Real; 

Printstring : String; 

Update_set : PVaryingType; 

Pr_I : Intl6; 


{include the GSR EXTERNAL declarations } 
“/.INCLUDE 'GSRLIB: PROEXTRN. PAS/nol i st' 
{include the GSR error handler} 

“/.INCLUDE 'GSRLIB:VAXERRHAN.PAS/nol ist' 


{These are the assembler routines to get exponents and mantissas} 
PROCEDURE PUPDEXP ( rnum: Real; VAR exp: Int8 ); EXTERN; 

PROCEDURE PUPDFRA ( rnum: Real; VAR mhi,mlo: Int8 ); EXTERN; 
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PROCEDURE VaxFp < rnum: Vaxreal; VAR exp.mhi,mlo: Int8 ); 

{ get the pieces of a USERUPD real from a VAX real } 

BEGIN 

PUPDEXP ( rnum.r, exp ); 

PUPDFRA ( rnum.r, mhl, mlo ); 

END; 

PROCEDURE Rangle ( angle: Real; VAR ahi,alo: IntS ); 

{ Get the pieces of a USERUPD angle from degrees } 

CONST 

Factor = 182.0444444; {magic number = 65536/360 } 

(to turn degrees in to 65536's of a circle} 

VAR 

itemp: Integer; 
myangle: real; 

BEGIN 

{ make any angle its equivalent in the range of 0 to 360 - 1/2**16 } 
my_angle:= angle; 

IF my_angle >= 0 THEN { the angle is positive ) 

BEGIN 

REPEAT {make the angle be 0>= angle < 360 } 

IF myangle >= 360 THEN 

my_angle:= my_angle - 360; 

UNTIL (myangle >= 0) AND (myangle < 360); 

End 

Else { the angle is negative ) 

BEGIN 

REPEAT {make the equivalent positive angle) 

IF my_angle < 0 THEN 

my_angle:= myangle + 360; 

UNTIL (My_angle >= 0) AND (my_angle < 360); 

End; 

itemp:= ROUND(My_angle * factor ); 
ahi := itemp DIV 256; 
alo := itemp MOD 256; 

END; 

PROCEDURE Rreal ( r: Real; VAR exp,mhi,mlo: Int8 ); 

{ copy a VAX real into the variant record and get the components > 
VAR 

rtt: Vaxreal; 

BEGIN 

rtt.r:=r; 

Vax_fp ( rtt, exp, mhi, mlo ); 

END; 
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PROCEDURE P_rot ( angle: Real; VAR Upd_angle: VARYING [len] OF CHAR ); 

{ make a 2-byte string that is a USERUPD angle } 

VAR 

hlangle.loangle: Int8; 

BEGIN 

Updangle.length:= 2; 

Rangle ( angle, hiangle, loangle ); 

UpdangleCl]:= CHR(hiangle) ; 

Upd_angleC2]:= CHR(loangle) ; 

END; 

PROCEDURE Pstring ( s: String; VAR UPDstrIng: PVarylngType ); 

{ make a USERUPD string; I.e., a 1-byte length and the string } 

VAR 

1s_1: Intl6; 

BEGIN 

Upd_str1ng.length:= s.length + 1; 

UPD_str1ng[l]:= CHR(s.length) ; 

FOR 1s_1 := 1 to s.length DO 
UPD_str1ng[1s_1 +1]:= s[1s_1]; 

END; 

PROCEDURE P_tran ( vec: Real; VAR UPD_trans: VARYING [len] OF CHAR ); 

{ make a 3-byte string that Is a UPD real used for translates } 

VAR 

exp,mh1,mlo: IntS; 

BEGIN 

Upd_trans.length:= 3; 

R_real ( vec, exp, mhl, mlo ); 

UPD_trans[l]:= CHR(exp); 

UPD_trans[2]:= CHR(mhl); 

UPD_trans[3]:= CHR(mlo); 

END; 

BEGIN 

{use the GSRs to attach to the PS 300's async Interface } 

PAttachC'LOGDEVNAM=TT:/PHYDEVTYP=ASYNC', ERRHAN); 

{ Multiplex to CIR0UTE<11> the Instance of USERUPD Is } 

{ connected there. } 

PMuxG( 9, ERRHAN ); 

Cnt := 3; { go through the sequence 3 times } 
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REPEAT 
Upl := 0; 

IncUpI ;= 1; 

Up2 := -90; 

IncUpZ := 0.5; 

Up3 := 90; 

IncUp3 := -0.25; 

Up4 := -90; 

IncUp4 := 0.5; 

Up5 := 0; 

IncUp5 ;= 1; 

Up6 := 1; 

IncUpS := -0.0022; 

FOR Pr I := 0 to 720 DO 


BEGIN 

Update_set.Length ;= 0; { 

{ 

Update_set:= CHR(6); { 

{ 

{ 

P_R0T(Upl,Current_angle); 
{ and concatenate it onto 
Update_set:= Update_set + 

P_R0T(Up2,Current_ang1e); 
Update_set;= Updateset + 

P_R0T(Up3,Current_ang1e); 
Update_set:= Updateset + 

P_R0T(Up4,Current_angle); 
Update_set:= Update_set + 

P_R0T(Up5,Current_angle); 
Update_set:= Updateset + 


nitiaize the update buffer} 
ength } 

every update set must start) 
with this character } 
get the angle } 

the update set } 
Current_ang1e; 


Currentangle; 


Currentangle; 


Currentangle; 


Currentangle; 


P_TRAN(Up6,Current_real); 

Update_set:= Updateset + Currentreal; 

Printstring := ' '; 

PrintString[3] :=CHR(trunc(Upl) MOD 10 + 48); 
PrintString[2] :=CHR(trunc(Upl/lO) MOD 10 + 48); 
PrintStringCl] :=CHR(trunc(Upl/lOO) MOD 10 + 48); 
P_STRING(Printstring,Currentstr); 

Update_set:= Updateset + Currentstr; 
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{ send the update set to the PS 300 } 

PPutG( Update_set. ERRHAN); 

{ make sure it goes now } 

PPurge( ERRHAN ); 

{ fix up the angles so that the arm ends up in its } 

{ initial position; e.g., upl goes from 0 to 359 and } 
{ back to 0 } 

IF PrJ = 360 THEN 
BEGIN 

IncUpl := -1.0; 

IncUp2 := -0.5; 

IncUp3 := 0.25; 

IncUp4 := -0.5; 

IncUp5 := -1.0; 

IncUp6 := 0.0022; 

END; 

Upl := Upl + IncUpl; 

Up2 := Up2 + IncUp2; 

Up3 := Up3 + IncUp3; 

Up4 := Up4 + IncUp4; 

Up5 := Up5 + IncUp5; 

Up6 := Up6 + IncUp6; 

END; { FOR pr_i } 

Cnt := Cnt - 1; 

UNTIL Cnt = 0; 

PDetach( ERRHAN ); 

END. 
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FUPDATE.FOR - FORTRAN EXAMPLE 



FUPDATE.FOR is a program example of how to use the F:USERUPD function to 
perform fast updates over an RS-232 communications line. This program is 
contained on the PS 300 magnetic tape labeled PSDIST and uses the E&S supplied 
GSR routines to send the data to ah instance of USERUPD. The program 
assumes that the file UPDATE.DAT has been loaded into the PS 300. 
UPDATE.DAT contains the data structures to be updated, and also instances 
F:USERUPD, initializes it and connects it to output <11> of CIRDUTEO. The 
program updates five rotation nodes, one translation node, and a character string. 

The structure being updated is a simple robot arm. Although the program does 
not demonstrate all updates that are possible using FrUSERUPD it does 
demonstrate a mechanism for building all of the data types that FrUSERUPD 
acknowledges. Refer to Volume 5 for instructions on compiling and linking this 
program. 

The program assumes that the error handling procedure is named "ERRHND" and 
that it resides in the same directory as the GSR files. 


Program Update 

REAL Upl,Up2,Up3,Up4,Up5,Up6 
REAL IncUpl,IncUp2,IncUp3,IncUp4,IncUp5,IncUp6 
CHARACTER Current_angle*2, Current_real*3, Current_str*5 
CHARACTER Update_set*20, Printstring*4 
C 

EXTERNAL ERRHND 
C 
C 

CALL PAttch(■LOGDEVNAM=TT:/PHYDEVTYP=ASYNC', ERRHND) 

C 

C Multiplex to CIR0UTE<11> 

C 

CALL PMuxG( 9, ERRHND ) 

C 

C Do the sequence 3 times 
C 

Cnt = 3 


o 
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1 CONTINUE 
Upl = 0. 

IncUpl = 1. 

Up2 = -90. 

IncUp2 = 0.5 
Up3 = 90. 

IncUp3 = -0.25 
Up4 = -90. 

IncUp4 = 0.5 
Up5 = 0. 

IncUp5 = 1. 

Up6 = 1. 

IncUp6 = -0.0022 
DO Pr_I =0 ,720 
C 

C The first character of an update set is always CHAR(6) 

C 

Update_set(l:1)= CHAR(6) 

C 

C Get the angle and put it in the Update set buffer 
C 

CALL P_R0T<Upl.Currentangle) 

Update_set(2:3) = Current_angle 

CALL P_ROT<Up2,Current_angle) 

Update_set(4:5)= Currentangle 

CALL P_R0T<Up3,Current_angle) 

Update_set(6:7)= Currentangle 

CALL P_ROT<Up4,Current_angle) 

Update_set(8:9)= Currentangle 

CALL P_ROT(Up5,Current_angle) 

Update_set(10:11)= Currentangle 

CALL P_TRAN(Up6,Current_real) 

Update_set(12:14)= Currentreal 

Printstring = ' ' 

PrintString(3:3) =CHAR(IMOD(IINT(Upl),10) + 48) 
PrintString(2:2) =CHAR(IMOD(IINT(Upl/lO),10) + 48) 
PrintStringCl:1) =CHAR(IMOD(IINT(Upl/lOO),10) + 48) 

CALL P_STRING(PrintString,Current_str) 

C 

C we know the length of the string so kludge it. 

C Fortran thinks the strings length is what it is declared 
C to be, Pascal lets you manipulate the length 
C 
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Update_set(15:19)= Currentstr 
C 

C Send the update set to the PS300 
C 

CALL PPutG( Update_set,19,ERRHND) 

C 

C Make sure it goes now 
C 

CALL PPurge( ERRHND ) 

C 

C Fix up the angles so that the arm ends up in its initial 
C position; e.g., Upl goes from 0 to 359 and back to 0 
C 

IF (Pr_I .eq. 360) THEN 
IncUpl = -1.0 
IncUp2 = -0.5 
IncUp3 = 0.25 
IncUp4 = -0.5 
IncUp5 = -1.0 
IncUp6 = 0.0022 

END IF 

Upl = Upl + IncUpl 
Up2 = Up2 + IncUp2 
Up3 = Up3 + IncUp3 
Up4 = Up4 + IncUp4 
Up5 = Up5 + IncUp5 
Up6 = Up6 + IncUp6 
END DO 

Cnt = Cnt - 1 
IF ( Cnt .gt. 0 ) GOTO 1 

CALL PDtach( ERRHND ) 

END 


o 




o o o o o o o 
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SUBROUTINE Vax_Fp (rnum, exp,mhi,mlo) 

C 

C Redundant routine left in so the FORTRAN looks like the Pascal version 
C 

C PUPDEXP and PUPDFRA are Macro routines to obtain the USERUPD 
C exponent and mantissa from a VAX real 
C 

REAL rnum 
BYTE exp, mhi,mlo 
CALL PUPDEXP ( rnum, exp ) 

CALL PUPDFRA ( rnum, mhi, mlo ) 

RETURN 

END 


SUBROUTINE R.angle ( angle, ahi,alo ) 


Get the pieces of a USERUPD angle from degrees 

REAL Factor, angle, my angle,temp 

INTEGER itemp 

BYTE ahi, alo, buff(2) 

EQUIVALENCE < itemp, buff) 

factor is a magic number to turn degrees into 
65536's of a circle 

Factor = 182.0444444 ! = 65536/360 

my_angle= angle 

IF (my_angle .ge. 0.0) THEN ! the angle is positive 
1 CONTINUE 

IF (myangle .ge. 360) THEN 
my_angle= myangle - 360.0 
END IF 

IF (my_ang1e .gt. 360) GOTO 1 
ELSE ! the angle is negative 
CONTINUE ! make the equivalent positive angle 
IF (my_angle .It. 0) THEN 
my_ang1e= my_ang1e + 360.0 


2 
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END IF 

IF (My angle .It. 0) GOTO 2 
END IF 

Temp = My angle * factor 
itemp= NINT( Temp ) 
ahi = buff(2) 
alo = buff(I) 

RETURN 

END 



SUBROUTINE R_real (r, exp,mhi,mlo ) 

C 

C Get the components of a USERUPD real 
C 

REAL r 

BYTE exp.mhi,mlo 

CALL Vax_fp ( r, exp, mhl, mlo ) 
RETURN 
END 


SUBROUTINE P rot ( angle, Upd_angle ) 

C 

C Get the components of a USERUPD angle 
C 

BYTE hiangle.loangle 
CHARACTER Upd_angle*(*) 

REAL angle 

CALL Rangle ( angle, hi angle, loangle ) 
Upd_angle(l:1)= CHAR(hiangle) 
Upd_angle(2:2)= CHARdoangle) 

RETURN 

END 


o o o 
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SUBROUTINE Pjtring (s, UPD_string ) 

C 

C make a USERUPD string; i.e., a 1-byte length and the string 
C 

INTEGER*2 is_i 

CHARACTER s*(*), Upd_string*(*) 

UPDstringCl:1)= CHAR(LEN(s)) 

UPD_string(2:) = s 
RETURN 
END 


SUBROUTINE P_tran ( vec,UPD_trans) 


Make a 3-byte string that is a USERUPD real 
REAL vec 

CHARACTER Upd_trans*(*) 

BYTE exp.mhi,mlo 

CALL R_real ( vec, exp, mhi, mlo ) 
UPD_trans(l:1)= CHAR(exp) 

UPD_trans(2:2)= CHAR(mhi) 

UPD_trans(3:3)= CHAR(mlo) 

RETURN 

END 


used for translates 


The following data are contained in the UPDATE.DAT file on the PSDIST 
magnetic tape and is used with the program examples. 


0 

CYLINDER:= VEC item N=100 


P 1.0000,1., 0.0000 L 
L 0.9686,0., 0.2487 L 
P 0.9686,1., 0.2487 L 
L 0.8763,0., 0.4818 L 
P 0.8763,1., 0.4818 L 
L 0.7290,0., 0.6845 L 
P 0.7290,1., 0.6845 L 
L 0.5358,0., 0.8443 L 
P 0.5358,1., 0.8443 L 
L 0.3090,0., 0.9511 L 


0.9686,1., 0.2487 
1 . 0000 , 0 ., 0.0000 
0.8763,1., 0.4818 
0.9686,0., 0.2487 
0.7290,1., 0.6845 
0.8763,0., 0.4818 
0.5358,1., 0.8443 
0.7290,0., 0.6845 
0.3090,1., 0.9511 
0.5358,0., 0.8443 



o 
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P 0.3090,1., 0.9511 L 0.0628,1., 0.9980 
L 0.0628,0., 0.9980 L 0.3090,0., 0.9511 
P 0.0628,1., 0.9980 L -0.1874,1., 0.9823 
L -0.1874,0., 0.9823 L 0.0628,0., 0.9980 
P -0.1874,1., 0.9823 L -0.4258,1., 0.9048 
L -0.4258,0., 0.9048 L -0.1874,0., 0.9823 
P -0.4258,1., 0.9048 L -0.6374,1., 0.7705 
L -0.6374,0., 0.7705 L -0.4258,0., 0.9048 
P -0.6374,1., 0.7705 L -0.8090,1., 0.5878 
L -0.8090,0., 0.5878 L -0.6374,0., 0.7705 
P -0.8090,1., 0.5878 L -0.9298,1., 0.3681 
L -0.9298,0., 0.3681 L -0.8090,0., 0.5878 
P -0.9298,1., 0.3681 L -0.9921,1., 0.1253 
L -0.9921,0., 0.1253 L -0.9298,0., 0.3681 
P -0.9921,1., 0.1253 L -0.9921,1.,-0.1253 
L -0.9921,0.,-0.1253 L -0.9921,0., 0.1253 
P -0.9921,1.,-0.1253 L -0.9298,1.,-0.3681 
L -0.9298,0.,-0.3681 L -0.9921,0.,-0.1253 
P -0.9298,1.,-0.3681 L -0.8090,1.,-0.5878 
L -0.8090,0.,-0.5878 L -0.9298,0.,-0.3681 
P -0.8090,1.,-0.5878 L -0.6374,1.,-0.7705 
L -0.6374,0.,-0.7705 L -0.8090,0.,-0.5878 
P -0.6374,1.,-0.7705 L -0.4258,1.,-0.9048 
L -0.4258,0.,-0.9048 L -0.6374,0.,-0.7705 
P -0.4258,1.,-0.9048 L -0.1874,1.,-0.9823 
L -0.1874,0.,-0.9823 L -0.4258,0.,-0.9048 
P -0.1874,1.,-0.9823 L 0.0628,1.,-0.9980 
L 0.0628,0.,-0.9980 L -0.1874,0. ,-0.9823 
P 0.0628,1.,-0.9980 L 0.3090,1.,-0.9511 
L 0.3090,0.,-0.9511 L 0.0628,0.,-0.9980 
P 0.3090,1.,-0.9511 L 0.5358,1.,-0.8443 
L 0.5358,0.,-0.8443 L 0.3090,0.,-0.9511 
P 0.5358,1.,-0.8443 L 0.7290,1.,-0.6845 
L 0.7290,0.,-0.6845 L 0.5358,0.,-0.8443 
P 0.7290,1.,-0.6845 L 0.8763,1.,-0.4818 
L 0.8763,0.,-0.4818 L 0.7290,0.,-0.6845 
P 0.8763,l.,-0.4818 L 0.9686,1.,-0.2487 
L 0.9686,0.,-0.2487 L 0.8763,0.,-0.4818 
P 0.9686,1.,-0.2487 L 1.0000,1., 0.0000 
L 1.0000,0., 0.0000 L 0.9686,0.,-0.2487 
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{WORLD SPACE ROTATIONS} 


XMUL := F:MULC; 
YMUL ;= F:MULC; 
ZMUL := F:MULC; 
XROT := FiXROTATE 
YROT := F:YROTATE 
ZROT := FrZROTATE 
CMUL := F:CMUL; 


CONN 

CONN 

CONN 

CONN 

CONN 

CONN 

CONN 

CONN 

CONN 

CONN 


DIALS <!>:<!> XMUL; 
DIALS <2>:<1> YMUL; 
DIALS <3>:<1> ZMUL; 
XMUL <!>:<!> XROT; 
YMUL <!>:<!> YROT; 
ZMUL <1>:<1> ZROT; 
XROT <1>:<2> CMUL; 
YROT <1>:<2> CMUL; 
ZROT <1>:<2> CMUL; 
CMUL <!>:<!> CMUL; 


SEND 150 TO <2> XMUL; 

SEND 150 TO <2> YMUL; 

SEND 150 TO <2> ZMUL; 

SEND M3D(1,0,0 0,1,0 0,0,1) TO <1> CMUL; 
SEND 'ROTATE X' TO <1> DLABELl; 

SEND 'ROTATE Y' TO <1> DLABEL2; 

SEND 'ROTATE V TO <1> DLABEL3; 


SCALE:=F:DSCALE; 

CONN DIALS <4>:<1> SCALE; 

CONN SCALE <2>:<3> SCALE; 

SEND 1 TO <2> SCALE; 

SEND 1 TO <3> SCALE; 

SEND 100 TO <4> SCALE; 

SEND 0 TO <5> SCALE; 

SEND ' SCALE ' TO <1> DLABEL4; 

XVEC:=F:XVECTOR; 

YVEC:=F:YVECTOR; 

ZVEC:=F:ZVECTOR; 

TRAN:=F:ACCUMULATE; 
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CONN DIALS <5>:<1> XVEC 
CONN DIALS <6>:<1> YVEC 
CONN DIALS <7>:<I> ZVEC 
CONN XVEC <1>:<1> TRAN 
CONN YVEC <1>:<1> TRAN 
CONN ZVEC <1>:<1> TRAN 


SEND V3D(0,0,0) TO <2> TRAN; 

SEND 'TRANS X' TO <1> DLABEL5; 

SEND 'TRANS Y' TO <1> DLABEL6; 

SEND 'TRANS Z' TO <I> DLABEL7; 



UP := F:userupd; 
configure a; 
disc cirouteO<i 1 >:al 1; 
conn cirouteO<l1>:<1>UPi; 
finish configuration; 

{ initialize the USERUPD function } 
send 

char(6) {mode character} 

&char(7) { do 7 updates } 

&char(2)&char(l) { y rot —> UPOOl } 

&char(l)&char(2) { x rot —> UP002 } 

&char(l)&char(3) { x rot —> UP003 } 

&char(l)&char(4) { x rot —> UP004 } 

&char(2)&char(5) { y rot —> UP005 > 

&char(5)&char(6) { x trans —> UP006 > 
&char(9)&char(7) { string —> UP007 } 
to <1>UP; 


INIT DISP; 

DISPLAY ROBOTARM; 


ROBOT_ARM:=BEGIN_S 

{WINDOW} 

Char scale .1 then UP007; 
TR:=TRANSLATE 0,0,0; 
RT:=R0TATE 0; 

SC:=SCALE .2; 

INST F00TING_C0L,UPOOl ; 
END_S; 

Up007 := Char -1,-.9 'XXXX'; 


O 
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FOOTING_COL:=SET COLOR 0,1 APPLIED TO FOOTING; 
FOOTING :=SCALE 3,-2,3 APPLIED TO CYLINDER; 


UPOOl:=ROTATE Y 0 APPLIED TO BASE_COL; 
BASE_COL:=SET COLOR 300,1 APPLIED TO BASE; 


BASE:=BEGIN_S 

TRANSLATE -2,7,0 
TRANSLATE 2,7,0 
TRANSLATE -2.5,0,0 
TRANSLATE 2.5,0,0 
SCALE 2 

TRANSLATE 0,7,0 
ENDS; 


APPLIED TO BASE_L_HUB; 
APPLIED TO BASE_R_HUB; 
APPLIED TO BASE_SUPPORT; 
APPLIED TO BASE_SUPPORT; • 
APPLIED TO CYLINDER; 
APPLIED TO UP002; 


BASE_L_HUB :=ROTATE Z 90 
BASE_R_HUB :=ROTATE Z -90 
BASE_SUPPORT:=SCALE .5,8,.5 


APPLIED TO CYLINDER; 
APPLIED TO CYLINDER; 
APPLIED TO CYLINDER; 


UP002:=ROTATE X -90 APPLIED TO PRIMARY_COL; 
PRIMARY_COL:=SET COLOR 240,1 APPLIED TO PRIMARY; 


PRIMARY:=BEGIN_S 
TRANSLATE 2,0,0 
TRANSLATE -.5,13,0 
TRANSLATE .5,13,0 
TRANSLATE -1,-4,0 
TRANSLATE l,-4,0 
TRANSLATE 1.5,-4,0 
TRANSLATE 0,13,0 
ENDS; 


APPLIED TO PRIMARY_PIVOT; 
APPLIED TO PRIMARY_L_HUB; 
APPLIED TO PRIMARY_R_HUB; 
APPLIED TO PRIMARY_SUPPORT; 
APPLIED TO PRIMARYSUPPORT; 
APPLIED TO PRIMARYTIE; 
APPLIED TO UP003; 


PRIMARYPIVOT :=ROTATE Z 90 APPLIED TO PRIMARY_PIVOTC; 

PRIMARY_L_HUB :=ROTATE Z 90 APPLIED TO CYLINDER; 

PRIMARY_R_HUB :=ROTATE Z -90 APPLIED TO CYLINDER; 

PRIMARY_SUPPORT:=SCALE .5,18,.5 APPLIED TO CYLINDER; 
PRIMARY_TIE :=ROTATE Z 90 APPLIED TO PRIMARYTIEC; 

PRIMARY_PIVOTC :=SCALE 1,4,1 APPLIED TO CYLINDER; 

PRIMARY_TIEC :=SCALE .5,3,.5 APPLIED TO CYLINDER; 


UP003;=R0TATE X 90 APPLIED TO SECONDARY_COL; 
SECONDARY_COL:=SET COLOR 180,1 APPLIED TO SECONDARY; 
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SECONDARY:=BEGINS 

TRANSLATE .5,11,0 APPLIED TO SECONDARY_HUB; 
TRANSLATE 0,-4,0 APPLIED TO SECONDARYSUPPORT; 

TRANSLATE .5,0,0 APPLIED TO SECONDARYHUB; 

TRANSLATE 0,11,0 APPLIED TO UP004; 

ENDS; 

SECONDARYHUB :=ROTATE Z 90 APPLIED TO CYLINDER; 
SECONDARY_SUPPORT:=SCALE .5,16,.5 APPLIED TO CYLINDER; 

UP004:=R0TATE X -90 APPLIED TO WRIST_COL; 

WRIST_COL:=SET COLOR 120,1 APPLIED TO WRIST; 

WRIST:=BEGIN_S 

TRANSLATE -.5,0,0 APPLIED TO WRIST_L_HUB; 

TRANSLATE .5,0,0 APPLIED TO WRISTRHUB; 

TRANSLATE -.85,-1,0 APPLIED TO WRIST_SUPPORT; 
TRANSLATE .85,-1,0 APPLIED TO WRISTSUPPORT; 

TRANSLATE 0,2,0 APPLIED TO WRISTPIVOT; 

TRANSLATE 0,2.5,0 APPLIED TO UP005; 

ENDS; 

WRIST_L_HUB :=ROTATE Z 90 APPLIED TO WRIST_HUB; 
WRIST_R_HUB :=ROTATE Z -90 APPLIED TO WRIST_HUB; 
WRIST_SUPPORT:=SCALE .35,3.0,.35 APPLIED TO CYLINDER; 
WRISTPIVOT :=SCALE 1.5,-.5,l.5 APPLIED TO CYLINDER; 
WRISTJUB :=SCALE 1,.5,1 APPLIED TO CYLINDER; 

UP005:=ROTATE X 0 APPLIED TO HANDCOL; 

HAND_COL:=SET COLOR 60,1 APPLIED TO HAND; 

HAND:=BEGIN_S 

SCALE 1.5,-.5,1.5 APPLIED TO CYLINDER; 
ROTATE Y 0 APPLIED TO UP006; 

ROTATE Y 90 APPLIED TO UP006; 

ROTATE Y 180 APPLIED TO UP006; 

ROTATE Y 270 APPLIED TO UP006; 

END_S; 

UP006:=TRANSLATE 1,0,0 APPLIED TO FINGER; 

FINGER:=SCALE .2,2,.2 APPLIED TO CYLINDER; 

CONN CMUL <!>:<!> ROBOT_ARM.RT; 

CONN SCALE <!>:<!> ROBOTARM.SC; 

CONN TRAN <!>:<!> ROBOT ARM.TR; 


> 
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HOST COMMUNICATION EXAMPLE 


Listed below is a FORTRAN subroutine called SHIP, which can be used in a 
VAX/VMS environment to provide easy host communication with a PS 300 data 
structure via the F:USERUPD function. This is a method to buffer USERUPD 
commands if you do not run the GSRs. 

Notice particularly the Configuration Mode statements mentioned in the 
subroutine's Comments Section. These statements must be included in your data 
structure to provide a link between the PS 300's host communication mechanisms 
and the F:USERUPD function. 

This subroutine is NOT contained on the PS 300 magnetic tape labeled PSDIST. 


C 

C ROUTINE TO SHIP A BUFFER IN COUNT MODE TO CIR0UTE0<8>. 

C 

C This routine sends the indicated string to CIR0UTE0<8> of the PS 300. 

C (The terminal must have been set to modes TTSYNC,NOWRAP,NOBROAD,EIGHTBIT.) 
C The PS 300 must have been configured with the following code: 

C 

C CONFIGURE A; 

C DISCONNECT CIR0UTE0<8>:ALL; 

C USERNOPl := F:NOP; 

C CONNECT CIROUTEO<8>:<1>USERNOP1; 

C FINISH CONFIGURATION; 

C 

C FORTRAN calling sequence: 

C 

C CALL SHIP(JBUF,ICT,IRATE) 

C 

C Where: 

C 

C JBUF is the LOGICAL*! buffer containing the data to be shipped (if ICT>0). 
C ICT is the INTEGER*2 byte count for JBUF. If ICT=0, then initial- 
C ization is assumed, and the first byte of JBUF is taken as the name 
C of the USERUPDATES function to be initialized. 

C IRATE is INTEGER*2 maximum update rate, in frames per second. If 
C this value is zero, update proceeds without any delay. (This 
C argument is noticed only when ICT=0.) 

C 



SUBROUTINE SHIP(JBUF,ICT,IRATE) 

C 

INCLUDE ■($IODEF)' 

C 

INTEGER*2 ICT.IKT,IRATE 
REAL DT,TIMED,TIME,T 

LOGICAL*) JBUFd),JKT(2),SIZ(4),INIT(68) 

EQUIVALENCE (IKT,JKT) 

C 

INTEGER*4 SYS$QIO,SYS$QIOW,CHAN,STATUS,STAT2,SYS$ASSIGN 
INTEGER*2 IOSB(4),IOSB2(4) 

CHARACTER*3 UNIT 

DATA ISW/0/,SIZ/6,0,0,'5'/,T,DT/2*0./ 

DATA INIT/6,0,65,'0', 


1 

■D', 

■I 

> 

S' , 

'C, 

'O' ,' 

N 

.'N' 

.'E' 

,;c;. 
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i 1 

> 
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'E', 
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N 
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.;p; 

> • > 
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> 
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A 

.'T' 

.'E' 

'S' 

5 

'C, 
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C 

.'T' 
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> 
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■E', 
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' >' 
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x' , 







IF( 

:isw. 

EQ. 

.0. 

OR. 

ICT. 

EQ.O) 

TIMEO 

=SECNDS(0 

IF( 

:isw. 

NE. 

.0) 

GO 

TO 

5 







ISW=1 

UNIT='TT:' 

STATUS=SYS$ASSIGN(UNIT,CHAN,,) 

IF(STATUS.EO.l) GO TO 5 
TYPE *,'BAD ASSIGN! — ',STATUS 
STOP 
C 

5 IF(ICT.NE.O) GO TO 10 
T=0. 

DT=0. 

IFdRATE.NE.O) DT=1./FLOAT(IRATE) 

INIT<28)=JBUF(1) 

INIT(67)=JBUF(1) 

C 

C This system call sends the array INIT to the PS 300 
C 

STAT2=SYS$0IOW( ,r.VAL(CHAN) ,%VAL(IO$_WRITEVBLK+IO$M_NOFORMAT 
1 +IO$M_CANCTRLO),I0SB2,,,INIT,%VAL(68),,,,) 

STATUS=STAT2 
GO TO 50 

t) 









o o o o 
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10 IKT=ICT+1 
SIZ(2)=JKT(2) 

SIZ(3)=JKT(1) 

T=T+DT 

C 

30 TIME=SECNDS(TIMEO) 

IF(TIME.LT.T) GO TO 30 
C 

C This system call sends the 4-byte count mode prefix to the PS 300. 

C 

C 

STAT2=SYS$0IOW(,%VAL(CHAN),ToVAL(IO$_WRITEVBLK+IO$M_NOFORMAT 
1 +I0$M_CANCTRL0). I0SB2,, ,SIZ ,mL(4),,,,) 

C 


This system call sends ICT bytes form buffer JBUF to the PS 300. 


STATUS=SYS$QIOW(,%VAL(CHAN).XVAKIO$_WRITEVBLK+IO$M_NOFORMAT 
1 +I0$M_CANCTRL0),I0SB,,, JBUF ,7.VAL( ICT),,,,) 

C 

50 IF(STATUS.EQ.l.AND.STAT2.EQ.1.AND.IOSB2(1).E0.1) RETURN 
TYPE ‘/COMMUNICATION ERROR! — STATUS = 

1 STATUS.STAT2,IOSB(l),IOSB2(l) 

STOP 

END 



ooooooooooooo 
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FLOATING POINT CONVERSION ROUTINE 


Following are two program segments, one written in FORTRAN and the other 
written in VAX assembly language. These segments convert standard VAX 
4-byte floating-point into the floating-point format expected by the 
F:USERUPD function. Both program segments are contained on the PS 300 
magnetic tape labeled PSDIST in the file TUB.MAR. 


CONVERSION ROUTINE FOR PS 300 FLOATING POINT NUMBERS 
Calling sequence: 

CALL FPCVTCA.JNUM) 


Where: 

A is the REAL*4 number to be converted. 

JNUM is the LOGICAL*! string of three bytes to receive the converted 
result. 

SUBROUTINE FPCVT(A.JNUM) 

REAL A 

LOGICAL*! JNUM(3) 

C 

CALL PUPDEXP<A,JNUM(1)) 

CALL PUPDFRA(A,JNUM(2),JNUM(3)) 

RETURN 

END 
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ASSEMBLY LANGUAGE CONVERSION ROUTINES 

•TITLE TLIB 
•IDENT /01/ 

; PUPDEXP—Return EXCESS 64 exponent of a real 
; Pascal calling sequence 

; PROCEDURE PUPDEXP ( r: Real; VAR exp: INT8 ); 

; FORTRAN calling sequence 
; SUBROUTINE PUPDEXP( r, exp ) 

; Where 

; R is REAL*4 number to be converted 
; exp is BYTE variable to return the exponent 

PUPDEXP:: 


WORD 

'M<R2, 

R3> 


MOVE 

@4(AP), 

R2 


ASHL 

#-7,R2, 

R3 ; 

Move into position 

BICL2 

rXFFFFFFOO, 

R3 ; 

Keep only exponent data 

BEQL 

1$ : 


If zero, leave it alone 

SUBL2 

#-64, 

R3 ; 

Else make it excess 64 

BICL2 

#^X80, 

R3 ; 

Clear sign-bit position 

ASHL 

#-8,R2, 

R2 ; 

Go get the sign bit 

BICL2 

#^XFFFFFF7F, 

R2 ; 

Clear all but sign bit 

BISB3 

R2,R3,@8(AP) 


Set sign 


RET 

; PUPDFRA—Return hi and low bytes of a real 
> 

; Pascal Calling sequence 

; PROCEDURE PUPDFRA ( r: Real; VAR mhi.mlo: IntB ); 

» 

; FORTRAN calling sequence 
; SUBROUTINE PUPDFRA( r, mhi, mio ) 

; Where 

; r is REAL*4 number to be converted 

; mhi, and mlo are BYTE variables to return the High and low bytes 
; of the mantissa 

PUPDFRA:: 

WORD "M<R2,R3,R4> 

MOVE 04(AP),R4 
ROTL #1,R4,R4 

BICB3 #'XFFFFFF00,R4,@8(AP) 

ROTL #8,R4,R4 

BICB3 rXFFFFFF00,R4,@12(AP) 

RET 


END 







